使用 API 密钥通过身份验证管理器进行身份验证

如需让智能体向 Google 地图或 Weather API 等外部工具进行身份验证,请在 Agent Identity 身份验证管理器中使用 API 密钥身份验证提供方配置出站身份验证。

API 密钥身份验证提供方会为您管理加密密钥。此功能无需在代理代码中对密钥进行硬编码或手动管理密钥。

API 密钥工作流

API 密钥身份验证提供方使用智能体的身份,不需要用户同意。Google 会采取措施,帮助确保 API 密钥在存储期间的安全。使用智能体开发套件 (ADK) 时,它会自动检索 API 密钥并将其注入到工具调用标头中。

准备工作

  1. 验证您是否选择了正确的身份验证方法。
  2. 启用 Agent Identity API(如果尚未启用)。

    启用 API 所需的角色

    如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

  3. 创建和部署智能体。

  4. 从您要连接的第三方服务获取 API 密钥。

  5. 验证您是否拥有完成此任务所需的角色。

所需的角色

如需获得创建和使用 API 密钥身份验证提供方所需的权限,请让管理员向您授予项目的以下 IAM 角色:

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含创建和使用 API 密钥身份验证提供方所需的权限。如需查看所需的确切权限,请展开所需权限部分:

所需权限

您需要具备以下权限才能创建和使用 API 密钥身份验证提供方:

  • 如需创建身份验证提供方,请执行以下操作: agentidentity.authProviders.create
  • 如需使用身份验证提供方,请执行以下操作:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

您也可以使用自定义角色或其他预定义角色来获取这些权限。

从第三方服务获取 API 密钥

在创建身份验证提供方之前,请从您希望代理连接到的第三方服务获取 API 密钥。

如果您要连接到 Google Cloud之外的第三方服务,请从该服务的开发者门户获取 API 密钥,并跳过本部分中的步骤。

如果您要连接到 Google Cloud 服务(例如 Cloud Translation 或 Google 地图),可以执行以下步骤来生成和配置 API 密钥:

  1. 在 Google Cloud 控制台中,为您的项目启用所需的 API 服务:

    1. 在 Google Cloud 控制台中,前往 API 和服务 > 库页面。

      前往“API 和服务”>“库”

    2. 搜索并启用代理使用的 API,例如 Cloud Translation API 或 Google 地图 Weather API。
    3. 复制生成的 API 密钥字符串。
  2. 配置 API 密钥:

    1. 在 Google Cloud 控制台中,前往 API 和服务 > 凭证页面。

      依次前往“API 和服务”>“凭证”

    2. 点击创建凭证 > API 密钥。
    3. 在创建 API 密钥对话框中,执行以下操作:
      1. 为 API 密钥输入一个唯一名称。
      2. 如需将密钥限制为您启用的特定 API,请从选择 API 限制列表中选择这些 API。
      3. 可选:在限制您的密钥以降低安全风险部分中,选择要限制访问权限的应用类型。
      4. 点击创建。
  3. 向服务终端节点发送测试请求,以验证您的 API 密钥。

    • 如需验证 Cloud Translation API 密钥,请运行以下命令:

      curl -X POST \
        -H "Content-Type: application/json" \
        -H "X-goog-api-key: YOUR_API_KEY" \
        -d '{"q": "Hello world", "target": "es"}' \
        "https://translation.googleapis.com/language/translate/v2"

      将 YOUR_API_KEY 替换为您生成的 API 密钥。

    • 如需验证 Google Maps Weather API 密钥,请运行以下命令:

      curl -X GET \
        "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"

      将 YOUR_API_KEY 替换为您生成的 API 密钥。

    如果 API 密钥有效且配置正确,服务会返回请求的数据。

创建 API 密钥身份验证提供方

创建身份验证提供方,以定义第三方应用的配置和凭据。

如需创建 API 密钥身份验证提供方,请使用 Google Cloud 控制台、Google Cloud CLI 或 REST API。

控制台

  1. 在 Google Cloud 控制台中,前往 Agent Registry 页面。

    前往 Agent Registry

  2. 点击要为其创建身份验证提供方的代理的名称。
  3. 点击身份。
  4. 在身份验证提供方部分中,点击 添加身份验证提供方。
  5. 在添加身份验证提供方窗格中,输入名称和说明。

    名称只能包含小写字母、数字或连字符,不能以连字符结尾,且必须以小写字母开头。

  6. 从 OAuth 类型列表中,选择 API 密钥。
  7. 点击创建并继续。
  8. 如需向您的智能体身份授予使用身份验证提供方的权限,请点击授予访问权限。

    此过程会自动将代理身份用户 (roles/agentidentity.user) 角色分配给身份验证提供方资源上的代理身份。

  9. 在身份验证提供方凭证部分,输入 API 密钥。
  10. 点击添加提供商配置。

新创建的身份验证提供方会显示在身份验证提供方列表中。

gcloud CLI

  1. 创建身份验证提供方:

    gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
        --project="PROJECT_ID" \
        --location="LOCATION" \
        --api-key="API_KEY"
  2. 验证您的身份验证提供方是否显示在列表中,并且其状态为 ENABLED:
    gcloud agent-identity auth-providers list \
       --project="PROJECT_ID" \
       --location="LOCATION"
  3. 授予访问权限,以便您的智能体和本地开发环境能够从身份验证提供方检索凭证。如需允许已部署的代理和您的个人用户账号访问身份验证提供方,请针对身份验证提供方资源授予 Agent Identity User (roles/agentidentity.user) 角色:

    1. 向已部署智能体的 SPIFFE ID(智能体身份)授予访问权限:

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
    2. 向您的个人用户账号授予访问权限,以便进行本地开发和测试 (adk web):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="user:USER_EMAIL"

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:身份验证提供方和智能体的部署位置(例如 us-west1)。
  • AUTH_PROVIDER_NAME:身份验证提供方的名称(例如 maps-api-key-authprovider)。
  • API_KEY:您从第三方服务生成的 API 密钥。
  • ORGANIZATION_ID:您的 Google Cloud 组织 ID。
  • PROJECT_NUMBER:您的 Google Cloud 项目编号。
  • ENGINE_ID:已部署的推理引擎智能体的 ID。
  • USER_EMAIL:您的个人用户账号邮箱。

REST

  1. 创建身份验证提供方:

    Agent Identity API 的 authProviders.create 方法会在项目和位置中创建 API 密钥身份验证提供方。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project。
    • LOCATION:身份验证提供方和代理的部署位置(例如 us-west1)。
    • AUTH_PROVIDER_NAME:身份验证提供方的名称(例如 maps-api-key-authprovider)。该名称只能包含小写字母、数字或连字符,不能以连字符结尾,并且必须以小写字母开头。
    • API_KEY:您从第三方服务生成的 API 密钥。

    HTTP 方法和网址:

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

    请求 JSON 正文:

    {
      "authProviderTypeParams": {
        "apiKey": {
          "apiKey": "API_KEY"
        }
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "name": "projects/my-project/locations/us-west1/authProviders/maps-api-key-authprovider",
      "createTime": "2026-04-03T21:15:41.367155Z",
      "updateTime": "2026-04-03T21:15:41.367155Z",
      "authProviderTypeParams": {
        "apiKey": {}
      },
      "state": "ENABLED"
    }
    
  2. 如需允许已部署的代理和您的个人用户账号从身份验证提供方检索凭据,请向身份验证提供方资源授予 Agent Identity User (roles/agentidentity.user) 角色:

    Agent Identity API 的 authProviders.setIamPolicy 方法可对身份验证提供方资源设置允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project。
    • LOCATION:身份验证提供方和代理的部署位置(例如 us-west1)。
    • AUTH_PROVIDER_NAME:身份验证提供方的名称。
    • ORGANIZATION_ID:您的 Google Cloud组织 ID。
    • PROJECT_NUMBER:部署代理的项目的数字 Google Cloud 项目编号(例如 987654321098)。
    • ENGINE_ID:已部署的推理引擎代理的 ID。
    • USER_EMAIL:您的个人用户账号邮箱。

    HTTP 方法和网址:

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

    请求 JSON 正文:

    {
      "policy": {
        "bindings": [
          {
            "role": "roles/agentidentity.user",
            "members": [
              "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
              "user:USER_EMAIL"
            ]
          }
        ]
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwYKmjvelug=",
      "bindings": [
        {
          "role": "roles/agentidentity.user",
          "members": [
            "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
            "user:alex@example.com"
          ]
        }
      ]
    }
    

在代理代码中进行身份验证

如需对智能体进行身份验证,您可以使用 ADK。

ADK

使用 ADK 中的 MCP 工具集在智能体代码中引用身份验证提供方。

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Google Cloud auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

示例:连接到 Google 地图 MCP

以下示例演示了将智能体连接到 Google 地图 MCP 服务器的 agent.py 配置:

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

maps_auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

maps_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://mapstools.googleapis.com/mcp"),
    auth_scheme=maps_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful "
        "information. You can also use your Google Maps tools to look up "
        "locations and directions."
    ),
    tools=[maps_tools],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

使用 ADK 中的经过身份验证的函数工具,在代理的代码中引用身份验证提供方。

示例:连接到 Google Maps Weather API

以下示例演示了如何配置 agent.py,以使用经过身份验证的函数工具将代理连接到 Google Maps Weather API:

import os
import httpx
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

weather_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

async def get_weather(credential: AuthCredential, latitude: float, longitude: float) -> str | dict:
    """Gets current weather conditions for a location."""
    api_key = None
    if http := credential.http:
        if http.additional_headers and "X-GOOG-API-KEY" in http.additional_headers:
            api_key = http.additional_headers["X-GOOG-API-KEY"]
        elif http.credentials and http.credentials.token:
            api_key = http.credentials.token

    if not api_key:
        return "Error: No API key available from the auth provider."

    params = {"location.latitude": latitude, "location.longitude": longitude, "key": api_key}
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://weather.googleapis.com/v1/currentConditions:lookup",
            params=params,
        )
        if response.status_code != 200:
            return f"Error from Weather API: {response.status_code} - {response.text}"
        return response.json()

get_weather_tool = AuthenticatedFunctionTool(
    func=get_weather, auth_config=weather_auth_config
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant. You will use your weather tool to "
        "look up current conditions."
    ),
    tools=[get_weather_tool],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

使用 ADK 中的 Agent Registry MCP 工具集在代理的代码中引用身份验证提供方。

您无需为此流程构建身份验证方案。MCP 服务器的出站绑定已记录要使用的身份验证提供方。

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

  

部署智能体

将代理部署到 Google Cloud时,请确保已启用代理身份。

Agent CLI

如果您使用的是智能体开发套件 (ADK) 和 Agent CLI,请按照以下步骤部署启用了智能体身份的智能体:

  1. 在代理应用文件夹中,创建一个名为 .agent_engine_config.json 的配置文件,以启用代理身份:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json
  2. 将智能体部署到 Gemini Enterprise Agent Platform 上的 Agent Runtime:

    uv run adk deploy agent_engine AGENT_NAME \
        --project="PROJECT_ID" \
        --region="LOCATION"

    替换以下内容:

    • AGENT_NAME:代理应用文件夹的名称(例如 maps_agent)。
    • PROJECT_ID:您的 Google Cloud项目 ID。
    • LOCATION:您要在其中部署智能体的受支持区域(例如 us-west1)。

Python SDK

如果您使用 Vertex AI Python SDK 以编程方式进行部署,请使用 identity_type=AGENT_IDENTITY 标志:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:您要在其中部署智能体的受支持区域(例如 us-west1)。

后续步骤