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

使用代理自身的身份向 Google Cloud 进行身份验证

智能体可以使用自己的身份访问 Google Cloud API 和其他资源。Google 建议在 Google Cloud 上托管的智能体使用此方法与其他 Google Cloud 服务互动。

当智能体自行行事时，它会使用其主要 SPIFFE 身份来请求 Google Cloud 访问令牌。

准备工作

所需角色

如需获得向智能体授予对 Google Cloud 服务的访问权限所需的权限，请让管理员向您授予目标资源的以下 IAM 角色：

如需授予对智能体的访问权限，请执行以下操作：
- Project IAM Admin (roles/resourcemanager.projectIamAdmin)
- Security Admin (roles/iam.securityAdmin)
建议为智能体身份授予的角色：
- Agent Context Editor (roles/aiplatform.agentContextEditor)
- Agent Default Access (roles/aiplatform.agentDefaultAccess)
- Vertex AI User (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
- Browser (roles/browser)
- Storage Object Viewer (roles/storage.objectViewer)

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

授予对智能体的访问权限

如需让智能体访问 Google Cloud 服务，您必须向智能体的身份授予目标资源所需的角色。

在 IAM 允许政策中，智能体身份使用 主账号标识符。

如需向智能体授予对资源的访问权限，请使用 Google Cloud 控制台或 gcloud CLI。

控制台

在 Google Cloud 控制台中，前往要授予访问权限的资源的 IAM 页面。
- 对于项目，请前往 IAM 页面：
  转到 IAM 页面
- 对于其他资源，请前往该资源的页面，然后点击权限或IAM标签页。
点击 授予访问权限。
在新的主账号 字段中，输入与您要授予的访问权限级别匹配的主账号标识符：
- 单个智能体: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- 项目中的所有智能体: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- 组织中的所有智能体: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
在选择角色 字段中，搜索并选择要授予的角色。
点击保存。

Google Cloud CLI

如需向智能体授予对资源的访问权限，请运行以下命令：

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

替换以下内容：

SERVICE： Google Cloud 服务（例如 storage 或 bigquery）。
RESOURCE_NAME：资源的名称（例如存储桶名称或数据集 ID）。
PRINCIPAL_IDENTIFIER：与您要授予的访问权限级别匹配的主账号标识符：
- 单个智能体：principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- 项目中的所有智能体：principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- 组织中的所有智能体：principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
ORGANIZATION_ID：您的 Google Cloud 组织 ID。
PROJECT_NUMBER：您的 Google Cloud 项目编号。
LOCATION：智能体的位置（例如 us-central1）。（仅当授予对单个智能体的访问权限时需要）
ENGINE_ID：推理引擎的 ID。（仅当授予对单个智能体的访问权限时需要）
ROLE：您要授予的 IAM 角色。

在代码中引用智能体身份

当智能体部署到受支持的 Google Cloud 环境时， Google Cloud 客户端库会自动使用 Agent Identity。

以下 Python 代码段展示了如何使用 Agent Identity 凭据通过智能体开发套件 (ADK) 手动调用 Cloud Vision API。

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

可选：选择停用与证书绑定的令牌

默认的 Google 管理的情境感知访问权限政策有助于保护 Agent Identity 凭据。除了 Agent Gateway 之外，该政策还通过对智能体的访问令牌进行身份验证来强制执行 Demonstrating Proof of Possession (DPoP)。该政策还要求使用双向 TLS (mTLS) 访问 Agent Gateway。此要求有助于确保只有预期的可信运行时环境（例如 Cloud Run 容器或 Google Kubernetes Engine (GKE) Pod）可以使用与证书绑定的令牌。此安全基准可确保被盗凭据无法重放，有助于防范凭据盗窃和账号入侵 (ATO)。

证书绑定有助于保护两种类型的智能体凭据：

Google Cloud 访问令牌：用于对 Google Cloud API 和其他资源 (*.googleapis.com) 的请求进行身份验证的短期 OAuth 2.0 访问令牌。
OpenID Connect (OIDC) ID 令牌：用于对外部服务以及托管在 Google Cloud 运行时（例如 Cloud Run (*.mtls.run.app) 或 GKE）中的工具和服务的请求进行身份验证的 JSON Web 令牌 (JWT)。

选择停用所有访问令牌和 ID 令牌的绑定

在整个运行时环境中选择停用默认的情境感知访问权限政策和与证书绑定的令牌不建议。设置 GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false会移除对 Google Cloud 访问令牌和 OIDC ID 令牌的令牌绑定保护，导致这些短期令牌容易被盗或受到重放攻击。

不过，在以下少数情况下，您可以在整个运行时环境中选择停用：

您对智能体之间的令牌共享有特定要求。
您必须将令牌直接注入到请求标头中。
您的智能体无法进行身份验证，并返回 401 UNAUTHENTICATED 错误。

如需在整个运行时环境中选择停用，请在部署智能体时设置以下环境变量：部署智能体

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

选择停用对单个 ID 令牌请求的绑定

默认情况下，受支持的 Google Auth 客户端库通过在令牌的 cnf (x5t#S256) 声明中添加证书指纹，以加密方式将 OIDC ID 令牌绑定到智能体的唯一 X.509 证书。

某些服务（例如 Cloud Run）会在 cnf 声明存在时强制执行证书绑定。如果您的智能体通过非 mTLS 端点（例如标准 *.run.app 网址）调用这些服务，或者目标端点不需要证书绑定，您可以选择停用对单个 ID 令牌请求的绑定。此设置仅影响该请求，不会停用对 Google Cloud 访问令牌的证书绑定。

Python

在 Python google-auth 库（GKE 上为 2.61.0 或更高版本，Cloud Run 上为 2.62.0 或更高版本）中，设置 bind_id_token=False：

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

将 TARGET_SERVICE_URL 替换为智能体调用的接收服务的受众 URI 或网址。

部署智能体

将智能体部署到 Google Cloud时，请确保已启用 Agent Identity 。如果您要部署到 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]"],
    },
)