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)
- 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 客户端库会自动使用智能体身份。

以下 Python 代码段展示了如何使用智能体开发套件 (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 Gateway 之外，该政策还会通过对智能体的访问令牌进行身份验证来强制执行 Demonstrating Proof of Possession (DPoP)。该政策还要求使用双向 TLS (mTLS) 访问 Agent Gateway。此要求有助于确保只有预期的可信运行时环境（例如 Cloud Run 容器或 Google Kubernetes Engine [GKE] Pod）才能使用绑定了证书的令牌。此安全基准可使被盗凭据无法重放，从而有助于防范凭据盗窃和账号入侵 (ATO)。

证书绑定有助于保护两种类型的代理凭据：

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

为所有访问令牌和 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时，请确保已启用代理身份。如果您要部署到 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]"],
    },
)