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

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

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

两方模式 OAuth 身份验证提供方会为您管理凭据和令牌。这样便无需编写自定义代码来处理身份验证流程。

两方模式 OAuth 工作流程

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

准备工作

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

所需的角色

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

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

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

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

所需权限

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

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

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

创建双向身份验证提供方

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

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

控制台

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

名称只能包含小写字母、数字或连字符，不能以连字符结尾，且必须以小写字母开头。
在 OAuth Type（OAuth 类型）列表中，选择 OAuth (2 legged)（OAuth [双方模式]）。 .
点击创建并继续。
如需向您的代理身份授予使用身份验证提供程序的权限，请点击授予访问权限。
这会自动向身份验证提供方资源上的代理身份分配 Connector User (roles/iamconnectors.user) 角色。
在身份验证提供方凭据部分中，输入以下信息：
- 客户端 ID (Client ID)
- 客户端密钥 (Client Secret)
- 令牌网址
点击添加提供商配置。

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

gcloud CLI

创建身份验证提供方：

gcloud alpha agent-identity connectors 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 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：身份验证提供方的名称（例如 jira-mcp-2lo-authprovider）。
CLIENT_ID：您从第三方服务生成的 OAuth 客户端 ID。
CLIENT_SECRET：您从第三方服务生成的 OAuth 客户端密钥。
TOKEN_ENDPOINT：令牌端点网址（例如 https://oauth2.googleapis.com/token）。
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],
)

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="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 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="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]"],
    },
)