如需让智能体对 Google 地图或 Weather API 等外部工具进行身份验证,请使用 Agent Identity 身份验证管理器中的 API 密钥身份验证提供方配置出站身份验证。
API 密钥身份验证提供方会为您管理加密密钥。借助此功能,您无需在智能体的代码中硬编码密钥,也无需手动管理密钥。
API 密钥工作流
API 密钥身份验证提供方使用智能体的身份,不需要用户同意。 Google 会采取措施,帮助确保 API 密钥在存储期间的安全。当您使用智能体开发套件 (ADK) 时,它会自动检索 API 密钥并将其注入到工具调用标头中。
准备工作
- 确认您已选择正确的身份验证方法。
启用 Agent Identity Connector API。
启用 API 所需的角色
如需启用 API,您需要拥有
serviceusage.services.enable权限。如果您 创建了项目,则可能已通过 所有者角色 (roles/owner) 拥有此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。从要连接的第三方服务获取 API 密钥。
确认您拥有完成 此任务所需的角色。
所需角色
如需获得创建和使用 API 密钥身份验证提供方所需的权限,请让您的管理员为您授予项目的以下 IAM 角色:
-
如需创建身份验证提供方:
- IAM Connector Admin (
roles/iamconnectors.admin) - IAM Connector Editor (
roles/iamconnectors.editor)
- IAM Connector Admin (
-
如需使用身份验证提供方:
- IAM Connector User (
roles/iamconnectors.user) - Vertex AI User (
roles/aiplatform.user) - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer)
- IAM Connector User (
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含 创建和使用 API 密钥身份验证提供方所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需创建和使用 API 密钥身份验证提供方,需要以下权限:
-
如需创建身份验证提供方:
iamconnectors.connectors.create -
如需使用身份验证提供方:
-
iamconnectors.connectors.retrieveCredentials -
aiplatform.endpoints.predict -
aiplatform.sessions.create
-
从第三方服务获取 API 密钥
在创建身份验证提供方之前,请从您希望智能体连接的第三方服务获取 API 密钥。
如果您要连接到外部的第三方服务 Google Cloud, 请从该服务的开发者门户获取 API 密钥,并跳过 本部分中的步骤。
如果您要连接到 Google Cloud 服务(例如 Cloud Translation 或 Google 地图),可以按照以下 步骤生成和配置 API 密钥:
-
在 Google Cloud 控制台中,为您的 项目启用所需 API 服务:
- 在 Google Cloud 控制台中,前往 API 和服务 >库 页面。
- 搜索并启用智能体使用的 API,例如 Cloud Translation API 或 Google Maps Weather API。
- 复制生成的 API 密钥字符串。
配置 API 密钥:
- 在 Google Cloud 控制台中,前往 API 和服务 >凭据 页面。
- 依次点击创建凭据>API 密钥。
- 在创建 API 密钥 对话框中,执行以下操作:
- 为 API 密钥输入唯一名称。
- 如需将密钥限制为已启用的特定 API,请从 选择 API 限制 列表中选择这些 API。
- 可选:在限制您的密钥以降低安全风险 部分中,选择应用类型以限制访问权限。
- 点击创建 。
-
向服务端点发送测试请求,以验证 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 页面。
- 点击要为其创建身份验证提供方的智能体的名称。
- 点击身份 。
- 在 Auth Providers 部分中,点击 Add auth provider 。
-
在 Add auth provider 窗格中,输入名称和说明。
名称只能包含小写字母、数字或连字符,不能以连字符结尾,并且必须以小写字母开头。
- 在 OAuth Type 列表中,选择 API key .
- 点击创建并继续 。
- 如需授予智能体身份使用身份验证提供方的权限,请点击授予访问权限 。
这会自动将 Connector User (
roles/iamconnectors.user) 角色分配给 身份验证提供方资源上的智能体身份。 - 在 Auth provider credentials 部分中,输入 API key 。
- 点击添加提供方配置 。
新创建的身份验证提供方会显示在 Auth Providers 列表中。
Google Cloud CLI
-
创建身份验证提供方:
gcloud alpha agent-identity connectors create
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --api-key="API_KEY" - 验证您的身份验证提供方是否显示在列表中,并且其状态为
ENABLED:gcloud alpha agent-identity connectors list \ --project="
PROJECT_ID" \ --location="LOCATION" -
授予访问权限,以允许智能体和本地开发环境 从身份验证提供方检索凭据。如需允许 已部署的智能体和您的个人用户账号访问身份验证 提供方,请在身份验证提供方 资源上授予 Connector User (
roles/iamconnectors.user) 角色:-
授予对已部署智能体的 SPIFFE ID(智能体身份)的访问权限:
gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/iamconnectors.user" \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID" -
授予对个人用户账号的访问权限,以便进行本地开发和测试 (
adk web):gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/iamconnectors.user" \ --member="user:USER_EMAIL"
-
替换以下内容:
PROJECT_ID:您的 Google Cloud 项目 ID。LOCATION:身份验证提供方和智能体的部署位置(例如us-west1)。AUTH_PROVIDER_NAME:身份验证提供方的名称(例如bigquery-mcp-3lo-authprovider)。AUTHORIZATION_URL:授权服务器网址(例如https://accounts.google.com/o/oauth2/v2/auth)。TOKEN_URL:令牌服务器网址(例如https://oauth2.googleapis.com/token)。CLIENT_ID:您从第三方服务生成的 OAuth 客户端 ID。CLIENT_SECRET:您从第三方服务生成的 OAuth 客户端密钥。ORGANIZATION_ID:您的 Google Cloud 组织 ID。PROJECT_NUMBER:您的 Google Cloud 项目编号。ENGINE_ID:已部署的推理引擎智能体的 ID。USER_EMAIL:您的个人用户账号电子邮件地址。
在智能体代码中进行身份验证
如需对智能体进行身份验证,您可以使用 ADK。
ADK
使用 ADK 中的 MCP 工具集在智能体的代码中引用身份验证提供方。
from google.adk.agents.llm_agent import LlmAgent 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 the Google Cloud auth provider so the CredentialManager can use it. CredentialManager.register_auth_provider(GcpAuthProvider()) # Create the Google Cloud auth provider scheme using the auth provider's full resource name. auth_scheme = GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent( 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" # 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/connectors/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.llm_agent import LlmAgent 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 spotify_auth_config = AuthConfig( auth_scheme=GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/connectors/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