Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用双方模式 OAuth 和身份验证管理器进行身份验证

如需让智能体使用自己的授权向 ServiceNow 或 Salesforce 等外部工具进行身份验证，请在“智能体身份”身份验证管理器中，使用双方模式 OAuth（客户端凭据）身份验证提供方配置出站身份验证。

通过管理凭据和令牌，双方模式 OAuth 身份验证提供方无需使用自定义代码来处理身份验证流程

两方模式 OAuth 工作流程

双向 OAuth 身份验证提供方使用代理的身份，不需要用户同意。Google 会管理客户端凭据的存储。使用智能体开发套件 (ADK) 时，它会自动检索生成的访问令牌并将其注入到工具调用标头中。

准备工作

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

所需的角色

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

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

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

这些预定义角色包含创建和使用双重身份验证代理身份验证提供程序所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建和使用双腿代理身份验证提供程序，您需要具备以下权限：

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

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

创建双向身份验证提供方

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

如需创建双向身份验证提供方，请使用 gcloud CLI：

创建身份验证提供方：

gcloud alpha agent-identity authProviders create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --two-legged-oauth-client-id="CLIENT_ID" \
    --two-legged-oauth-client-secret="CLIENT_SECRET" \
    --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT"

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

gcloud alpha agent-identity authProviders list \
   --project="PROJECT_ID" \
   --location="LOCATION"

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

向已部署代理的 SPIFFE ID（代理身份）授予访问权限：

gcloud alpha agent-identity authProviders 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 alpha agent-identity authProviders 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：身份验证提供方的名称（例如 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
# 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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="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
# 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 = LlmAgent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="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
# 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 = LlmAgent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

安装用于本地测试的依赖项

如需在虚拟环境中本地测试代理，请安装以下必需的依赖项：

创建并激活虚拟环境：

python3 -m venv env
source env/bin/activate

安装必需的软件包：

pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

部署智能体

将智能体部署到 Google Cloud时，请确保已启用智能体身份。

如果您要部署到 Gemini Enterprise Agent Platform 上的 Agent Runtime，请使用 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]"],
    },
)