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

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

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

双方模式 OAuth 工作流

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

准备工作

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

所需角色

如需获得创建和使用双腿模式 Agent Identity Auth 提供方所需的权限，请让您的管理员为您授予项目的以下 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)

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

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

所需权限

您需要具备以下权限才能创建和使用双方模式 Agent Identity 身份验证提供方：

如需创建身份验证提供方： iamconnectors.connectors.create
如需使用身份验证提供方：
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

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

创建双方模式身份验证提供方

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

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

控制台

在 Google Cloud 控制台中，前往 Agent Registry 页面。
前往 Agent Registry
点击要为其创建身份验证提供方的智能体的名称。
点击身份。
在 Auth Providers 部分中，点击 Add auth provider 。
在 Add auth provider 窗格中，输入名称和说明。

名称只能包含小写字母、数字或连字符，不能以连字符结尾，并且必须以小写字母开头。
在 OAuth Type 列表中，选择 OAuth (2 legged) .
点击创建并继续 。
如需授予智能体身份使用身份验证提供方的权限，请点击授予访问权限 。
这会自动将 Connector User (roles/iamconnectors.user) 角色分配给身份验证提供方资源上的智能体身份。
在 Auth provider credentials 部分中，输入以下信息：
- 客户端 ID
- 客户端密钥
- 令牌网址
点击添加提供方配置 。

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

Google Cloud 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"

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

Agent Identity 基于行业标准的 SPIFFE ID 格式。在 IAM 允许政策中，智能体身份使用主账号标识符 来引用。

项目级 (gcloud)

在项目级授予角色可让智能体使用该项目中的任何身份验证提供方。

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

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 中的 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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_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时，请确保已启用 Agent Identity 。

如果要部署到 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]"],
    },
)