Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

如需让智能体向 Google 地图或天气 API 等外部工具进行身份验证，请在“智能体身份”身份验证管理器中配置使用 API 密钥身份验证提供程序的出站身份验证。

API 密钥身份验证提供程序会为您管理加密密钥。借助此功能，您无需在代理的代码中硬编码密钥，也无需手动管理密钥。

API 密钥工作流

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

准备工作

确认您已选择正确的身份验证方法。
启用 Agent Identity API。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
启用 API
创建和部署代理。
从要连接的第三方服务获取 API 密钥。
验证您是否拥有完成此任务所需的角色。

所需的角色

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

如需创建身份验证提供方，请执行以下操作：
- Agent Identity Admin (roles/agentidentity.admin)
- Agent Identity Editor (roles/agentidentity.editor)
如需使用身份验证提供方，请执行以下操作：
- Agent Identity User (roles/agentidentity.user)
- Vertex AI User (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

这些预定义角色包含创建和使用 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 密钥：

在 Google Cloud 控制台中，为您的项目启用所需的 API 服务：
1. 在 Google Cloud 控制台中，前往 API 和服务 > 库页面。
  前往“API 和服务”>“库”
2. 搜索并启用代理使用的 API，例如 Cloud Translation API 或 Google Maps Weather API。
3. 复制生成的 API 密钥字符串。
配置 API 密钥：
1. 在 Google Cloud 控制台中，前往 API 和服务> 凭据页面。
  前往“API 和服务”>“凭据”
2. 依次点击创建凭据> API 密钥。
3. 在创建 API 密钥 对话框中，执行以下操作：
  1. 为您的 API 密钥输入一个唯一的名称。
  2. 如需将密钥限制为仅可访问您启用的特定 API，请从选择 API 限制列表中选择这些 API。
  3. 可选：在限制您的密钥以降低安全风险部分中，选择要限制访问权限的应用类型。
  4. 点击创建。
通过向服务端点发送测试请求来验证您的 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。

控制台

在 Google Cloud 控制台中，前往 Agent Registry 页面。
前往 Agent Registry
点击要为其创建身份验证提供程序的代理的名称。
点击身份。
在身份验证提供方部分中，点击 添加身份验证提供方。
在添加身份验证提供方窗格中，输入名称和说明。

名称只能包含小写字母、数字或连字符，不能以连字符结尾，且必须以小写字母开头。
在 OAuth 类型列表中，选择 API 密钥。
点击创建并继续。
如需向您的代理身份授予使用身份验证提供程序的权限，请点击授予访问权限。
此过程会自动向身份验证提供方资源上的代理身份分配 Agent Identity User (roles/agentidentity.user) 角色。
在身份验证提供程序凭据部分中，输入 API 密钥。
点击添加提供商配置。

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

gcloud CLI

创建身份验证提供方：

gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --api-key="API_KEY"

验证您的身份验证提供程序是否显示在列表中，以及其状态是否为 ENABLED：

gcloud agent-identity auth-providers list \
   --project="PROJECT_ID" \
   --location="LOCATION"

授予访问权限，以允许您的代理和本地开发环境从身份验证提供方检索凭据。如需允许已部署的代理和您的个人用户账号访问身份验证提供方，请向身份验证提供方资源授予 Agent Identity User (roles/agentidentity.user) 角色：

向已部署的代理的 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"

为本地开发和测试授予对您的个人用户账号的访问权限 (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 对智能体进行身份验证。

注意：以下示例在模块级注册了身份验证提供程序，当您在本地运行代理或使用 Agent CLI 部署代理时，此方法有效。如果您使用 Vertex AI Python SDK 进行部署，请在 set_up() 中注册身份验证提供程序，以便在已部署的容器中运行。如需了解详情，请参阅部署代理。

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 中的 Agent Registry MCP 工具集在代理的代码中引用身份验证提供方。

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

注意：请为身份验证提供程序、MCP 服务器和 Agent Registry 客户端使用同一区域。身份验证提供程序在 global 位置不可用，因此如果您设置 location="global"，则创建出站绑定会失败，并显示错误

Location of auth provider does not
match location of binding

。

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 Identity。

Agent CLI

如果您使用的是智能体开发套件 (ADK) 和智能体 CLI，请按以下步骤操作，以部署启用了智能体身份的智能体：

在代理应用文件夹中，创建一个名为 .agent_engine_config.json 的配置文件，以启用 Agent Identity：
```
echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json
```
将智能体部署到 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 标志：

注意：SDK 会序列化您的应用对象，因此本地脚本在导入时运行的 CredentialManager.register_auth_provider() 调用不会在已部署的容器中运行。请改为在应用的 set_up() 方法中注册身份验证提供程序，运行时会在容器启动时调用该方法。否则，代理会在查询时失败并显示

No auth provider registered for custom
auth scheme 'gcpAuthProviderScheme'

。如需了解详情，请参阅部署注意事项。

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）。

使用 API 密钥通过身份验证管理器进行身份验证 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

API 密钥工作流

准备工作

所需的角色

所需权限

从第三方服务获取 API 密钥

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

控制台

gcloud CLI

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

ADK

示例：连接到 Google 地图 MCP

ADK

示例：连接到 Google Maps Weather API

ADK

部署智能体

Agent CLI

Python SDK

后续步骤

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