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

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

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

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

两方模式 OAuth 工作流

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

准备工作

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

所需的角色

如需获得创建和使用 2-legged Agent Identity 身份验证提供方所需的权限，请让您的管理员为您授予项目的以下 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)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

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

所需权限

如需创建和使用 2-legged 代理身份验证提供方，您需要具备以下权限：

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

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

创建 2-legged 身份验证提供方

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

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

控制台

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

名称只能包含小写字母、数字或连字符，不能以连字符结尾，且必须以小写字母开头。
从 OAuth Type（OAuth 类型）列表中，选择 OAuth (2 legged)（OAuth [两方模式]）。
点击创建并继续。
如需向您的智能体身份授予使用身份验证提供方的权限，请点击授予访问权限。
这会自动将 Connector User (roles/iamconnectors.user) 角色分配给身份验证提供方资源上的代理身份。
在Auth 提供方凭证部分中，输入以下信息：
- 客户端 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 中的 Agent Registry 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]"],
    },
)