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 访问令牌。

准备工作

所需角色

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

如需向代理授予访问权限，请执行以下操作：
- 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：服务（例如 storage 或 bigquery）。 Google Cloud
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 访问代理网关。这可确保绑定到证书的令牌只能从其预期的受信任运行时环境（例如 Cloud Run 容器）中使用。此安全基准可确保被盗凭据无法重放，有助于防范凭据盗窃和账户接管（攻击）(ATO)。

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

如需选择停用，请在部署代理时设置以下环境变量：

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

部署智能体

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