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

如需让您的代理对 Google 地图或 Weather API 等外部工具进行身份验证，请使用代理身份验证管理器中的 API 密钥身份验证提供方配置出站身份验证。

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

API 密钥工作流

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

准备工作

确认您已选择正确的身份验证方法。
启用 Agent Identity Connector API。
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。
启用 API
创建并部署代理。
从要连接的第三方服务获取 API 密钥 。
确认您拥有完成此任务所需的角色。

所需角色

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

如需创建身份验证提供方，请授予以下角色：
- IAM Connector Admin (roles/iamconnectors.admin)
- IAM Connector Editor (roles/iamconnectors.editor)
如需使用身份验证提供方，请授予以下角色：
- IAM Connector User (roles/iamconnectors.user)
- Agent Default Access (roles/aiplatform.agentDefaultAccess)
- Agent Context Editor (roles/aiplatform.agentContextEditor)
- Vertex AI User (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

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

所需权限

创建和使用 API 密钥身份验证提供方需要以下权限：

如需创建身份验证提供方，请授予以下权限： iamconnectors.connectors.create
如需使用身份验证提供方，请授予以下权限：
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

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

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

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

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

控制台

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

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

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

Google Cloud CLI

创建身份验证提供方：

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --api-key="API_KEY"

如需授予代理身份使用身份验证提供方的权限，请更新项目或特定身份验证提供方的 IAM 允许政策，并将 Connector User (roles/iamconnectors.user) 角色授予代理正文。

代理身份基于行业标准的 SPIFFE ID 格式。在 IAM 允许政策中，代理身份使用主账号标识符 进行引用。

项目级 (gcloud)

在项目级层授予角色后，代理可以使用该项目中的任何身份验证提供方。

如需向单个代理授予对项目中身份验证提供方的访问权限，请运行以下命令：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/iamconnectors.user' \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

如需向项目中的所有代理授予对 Auth 提供方的访问权限，请运行以下命令：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/iamconnectors.user' \
    --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"

连接器级 (curl)

如需向单个代理授予对特定身份验证提供方的访问权限，请使用 setIamPolicy API。此命令会覆盖资源上的任何现有允许政策。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
AUTH_PROVIDER_NAME：身份验证提供方的名称。
ORGANIZATION_ID：您的 Google Cloud 组织 ID。
PROJECT_NUMBER：您的 Google Cloud 项目编号。
LOCATION：代理的位置（例如 us-central1）。
ENGINE_ID：推理引擎的 ID。

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

如需对代理进行身份验证，您可以使用 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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

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 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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

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

vertex_app = agent_engines.AdkApp(app_name=app)

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
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 by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

部署智能体

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

如果要部署到代理运行时，请使用 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]"],
    },
)