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

如需让智能体向 Google 地图或天气 API 等外部工具进行身份验证，请在“智能体身份”身份验证管理器中配置使用 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 Maps 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。

控制台

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

    前往代理注册表

  2. 点击要为其创建身份验证提供程序的代理的名称。
  3. 点击身份。
  4. 在身份验证提供方部分中，点击 添加身份验证提供方。

  5. 在添加身份验证提供方窗格中，输入名称和说明。

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

  6. 在 OAuth Type（OAuth 类型）列表中，选择 API key（API 密钥）。 .
  7. 点击创建并继续。
  8. 如需向您的代理身份授予使用身份验证提供程序的权限，请点击授予访问权限。

    此过程会自动向身份验证提供方资源上的代理身份分配 Agent Identity User (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：您的个人用户账号电子邮件地址。

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

您可以使用 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 Maps 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 中的经过身份验证的函数工具，在代理的代码中引用身份验证提供方。

import httpx
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_identity import GcpAuthProviderScheme
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.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

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

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

示例：连接到 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 中的代理注册表 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_identity import 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
from google.adk.integrations.agent_registry import AgentRegistry

# First, 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"
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "global/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    auth_scheme=auth_scheme,
)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

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

部署智能体

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

Agent CLI

如果您使用的是智能体开发套件 (ADK) 和智能体 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

# 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")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(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）。

后续步骤