Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用代理的自有权限进行身份验证

智能体可以使用自己的授权来访问 Google Cloud API 和其他资源。我们建议使用此方法，以便在 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)
- 代理默认访问权限 (roles/aiplatform.agentDefaultAccess)
- Vertex AI User (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
- 浏览器 (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 管理的情境感知访问权限政策有助于保护代理身份凭据。除了代理网关之外，该政策还通过对代理的访问令牌进行身份验证来强制执行“所有权证明”(DPoP)。该政策还强制要求使用 mTLS 来访问 Agent Gateway。这样可确保证书绑定令牌只能从其预期的可信运行时环境（例如 Cloud Run 容器）中使用。此安全基准可使被盗凭据无法重放，有助于防范凭据盗窃和账号盗用 (ATO)。

在极少数情况下（例如代理之间存在特定的令牌共享要求），如果您需要直接在标头中注入令牌，或者您的代理无法通过 401 UNAUTHENTICATED 错误进行身份验证，您可以选择停用默认的上下文感知访问权限政策。选择停用后，系统会移除令牌绑定的保护措施，导致这些短期有效的访问令牌容易被盗或受到重放攻击。因此，我们不建议选择停用。

如需选择不启用此功能，请在部署代理时设置以下环境变量：

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

部署智能体

将代理部署到 Google Cloud时，请确保已启用代理身份。如果您要部署到 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]"],
    },
)