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

将代理身份与 Agent Runtime 搭配使用

在 Agent Runtime 上使用智能体身份可提供安全的每个智能体身份，从而实现最小权限访问管理方法。本文档介绍了如何创建具有智能体身份的智能体、授权访问Google Cloud API，以及管理第三方服务的凭据。

概览

智能体身份为每个智能体提供一个身份，该身份遵循最小权限原则，并与智能体的生命周期相关联，因此智能体身份是比服务账号更安全的安全主体。通过 IAM 支持 Agent Identity 的现有访问管理控制功能，从而实现强大的治理。

默认情况下，代理身份凭据通过 Google 管理的情境感知访问权限 (CAA) 政策进行保护。此政策会强制执行 mTLS 绑定，以确保代理以证书绑定令牌形式提供的凭据只能在其预期的可信运行时环境（例如 Cloud Run 容器）中使用。此安全基准可使被盗凭证无法重放，从而防范凭证盗窃和账号入侵 (ATO)。

本页面涵盖以下主题：

创建具有智能体身份的智能体：创建智能体，以便在部署到 Agent Runtime 时，智能体自动获得唯一身份。
使用代理身份授权访问 Google Cloud API：使用预配的代理身份授予或拒绝代理对 Google Cloud的第一方工具、API 和资源的访问权限。这还包括使用 Agent2Agent (A2A) 协议访问 Agent Runtime 上托管的其他智能体。
记录智能体活动：在 Google Cloud 服务的日志中查看智能体身份。对于用户委托的流程，日志会同时显示用户身份和代理身份。
列出智能体和智能体身份：在 Agent Runtime 中查看智能体及其身份的列表。
停用情境感知访问权限（不推荐）：停用默认的情境感知访问权限 (CAA) 政策。

限制

无法向代理身份授予 Cloud Storage 存储桶的旧版存储桶角色（storage.legacyBucketReader、storage.legacyBucketWriter 或 storage.legacyBucketOwner）。

使用智能体身份创建智能体

您可以在创建 Agent Runtime 实例时，为部署到 Agent Runtime 的智能体预配唯一身份。该身份与 Agent Runtime 的智能体资源 ID 相关联，并且与您用于开发智能体的智能体框架无关。

创建代理身份时，您有以下选项：

在不部署代理代码的情况下创建 Agent Runtime 实例：如果您想在部署代理之前设置 IAM 政策，则可以在不部署代理代码的情况下创建代理身份。为此，请创建一个仅包含 identity_type 字段的 Agent Runtime 实例：
```
import agentplatform
from agentplatform import types

client = agentplatform.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.runtimes.create(
  config={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)
```
使用智能体身份创建 Agent Runtime 实例后，您可以使用 client.runtimes.update(...) 添加智能体代码。

在部署代理代码时创建 Agent Runtime 实例：如果您想在部署代理代码时预配代理身份，请使用 Python 版 Agent Platform SDK 和 identity_type=AGENT_IDENTITY 标志。

在您首选的框架中定义智能体：

from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

然后，部署该应用：

import agentplatform
from agentplatform import types
from agentplatform.frameworks import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = agentplatform.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.runtimes.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-agentplatform[adk,runtimes]"],
    "staging_bucket": f"gs://"BUCKET_NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

其中，BUCKET_NAME 是 Cloud Storage 存储桶的名称。

使用 Agents CLI 部署智能体：Agents CLI 非常适合学习者、原型设计和快速测试，因为它提供了快速部署解决方案，并包含用于监控的基础资源。以下命令会部署您的智能体：
```
agents-cli deploy --agent-identity
```
使用 ADK deploy 部署具有智能体身份的智能体：使用 ADK 设置智能体。在运行 adk deploy 之前，请在智能体的文件夹中运行以下命令，以添加包含智能体身份的配置文件。
```
# Create the file
$ touch .agent_engine_config.json

# Update the file to specify that you're using Agent Identity
$ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json
```

Agent Runtime 实例是使用只读、系统认证的代理身份（主账号标识符）创建的：

# Agent identity Format
principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME

# Example agent identity
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

以下部分会作为代理身份的一部分自动预配给您：

TRUST_DOMAIN：启用 Agent Platform API 后，系统会为您预配一个信任域：
- 如果您有组织，则信任域会在组织级层创建，格式为 agents.global.org-ORGANIZATION_ID.system.id.goog。
- 如果您的项目没有组织，则系统会在项目级层创建一个信任域，格式为 agents.global.proj-PROJECT_NUMBER.system.id.goog。
NAMESPACE：智能体的不可变资源路径。
AGENT_NAME：不可变的 agent-reasoning-engine-id。

代理身份基于 SPIFFE。我们还会在代理上自动预配和管理具有相同身份的 x509 证书，以进行安全身份验证。默认情况下，智能体可以访问自己的日志记录、指标、模型访问权限、会话、记忆和沙盒（预览版）。

代理身份具有默认的 roles/aiplatform.agentContextEditor 和 roles/aiplatform.agentDefaultAccess 角色，因此代理具有基本的操作权限。

您可以通过 Agent Runtime Google Cloud 控制台和 API 查看身份。

使用代理身份访问 Google Cloud API 和服务

创建具有代理身份的代理后，您可以使用以下 IAM 政策授予或拒绝代理对 Google Cloud API 和服务的访问权限：

允许政策：向代理授予对 Google Cloud 资源的访问权限。
拒绝政策：拒绝代理访问 Google Cloud 资源。

授予对代理的访问权限

向智能体身份授予 IAM 权限。我们建议您使用以下角色：

roles/aiplatform.expressUser：授予对运行推理、会话和记忆功能的访问权限。
roles/serviceusage.serviceUsageConsumer：向智能体授予使用项目配额和 Agent Platform SDK 的权限。
roles/browser：授予对基本 Google Cloud 功能的访问权限。
roles/secretmanager.secretAccessor：向代理授予对 Secret Manager 中 Secret 的访问权限。如果您将 Secret 作为环境变量引用，则还必须向 Agent Platform 服务代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform.) 授予 roles/secretmanager.secretAccessor，以便其在部署期间检索 Secret 值。

如果您使用日志记录、指标和 Cloud API 注册表，以及您想向代理公开的任何其他资源，则可能需要其他权限。如需查看更多示例，请参阅下文。

创建 IAM 允许政策，以向代理授予 IAM 角色：

  # Example: Grant the agent access to vision API.
  gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="ROLE_NAME" \

替换以下内容：

RESOURCE_TYPE：资源类型（例如 projects 或 organizations）。
RESOURCE_ID：您要授予访问权限的资源的 ID。
ORGANIZATION_ID：您的组织的 ID。
PROJECT_NUMBER：您的项目编号。
LOCATION：您的区域。请参阅 Runtime 的受支持的国家/地区。
AGENT_ENGINE_ID：Agent Runtime 实例的资源 ID。
ROLE_NAME 是您要授予的角色的名称。例如 roles/vision.user。如需了解预定义角色的列表，请参阅了解角色。

配置 IAM 后，Agent Platform SDK 的应用默认凭证会自动使用智能体身份向Google Cloud 资源执行身份验证。

授予 Agent-to-Agent (A2A) 委托访问权限

在设计多智能体系统时，如果父智能体调用在智能体注册表中注册的远程子智能体，则父智能体的身份必须具有在智能体注册表中发现子智能体并调用其端点的权限。

为确保父智能体的身份具有发现和调用远程子智能体所需的权限，请让管理员向父智能体的身份授予以下 IAM 角色：

让父智能体在运行时查找子智能体的端点：父级项目或注册表资源上的 Agent Registry API Viewer (roles/agentregistry.viewer)
让父智能体向子智能体发送消息：目标子智能体的推理引擎资源上的 Agent Platform User (roles/aiplatform.user)

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

您的管理员还可以通过自定义角色或其他预定义角色向父智能体的身份授予所需的权限。

例如，如需授予项目的 roles/agentregistry.viewer 角色，您可以使用以下 Google Cloud CLI 命令：

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
    --role="roles/agentregistry.viewer"

替换以下内容：

ORGANIZATION_ID：您的组织的 ID。
PROJECT_NUMBER：您的项目编号。
LOCATION：父智能体的部署区域。
PARENT_AGENT_ENGINE_ID：父智能体的 Agent Runtime 实例的资源 ID。

向多个代理授予访问权限

您可以向特定项目或整个组织中的所有 Agent Runtime 智能体授予 IAM 角色。

如需向项目中的所有 Agent Runtime 代理授予角色，请使用以下命令之一。

如果您的项目属于某个组织：

# Grant all agents in a project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

如果您的项目不属于任何组织：

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.proj-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

为简化部署，您可以更轻松地向项目中的所有代理授予常见权限，例如配额、日志记录或对模型的访问权限。然后，向各个代理授予特定的窄权限，以获得更敏感的权限，例如访问数据。在组织或项目中首次使用代理身份功能后，可以随时授予此类权限，因此可以在部署代理之前执行此操作。

例如，以下命令会向项目中的所有代理授予基本角色：

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/browser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/aiplatform.expressUser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/cloudapiregistry.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/monitoring.metricWriter

如需向组织中的所有 Agent Runtime 智能体授予角色，请执行以下操作：

# Grant all agents in an organization the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platform/aiplatform" \
--role="ROLE_NAME"

拒绝访问代理

如需拒绝代理访问资源，您可以使用 IAM 拒绝政策或设置主账号访问权限边界政策。

使用 IAM 拒绝政策拒绝智能体访问某些资源。

// Deny policy (deny all agents across the org from ability to create or delete buckets)

{
"displayName": "Deny access to bucket for all agent identities in the org",
"rules": [
  {
    "denyRule": {
      "deniedPrincipals": [
        "principalSet://<org.id>.global.agent.id.goog/*"
      ],
      "deniedPermissions": [
        "iam.googleapis.com/roles.create",
        "storage.googleapis.com/buckets.delete"
      ]
    }
  }
]
}

设置 Principal Access Boundary，以限制代理可以访问的资源，而不考虑代理可能拥有的其他权限：

// PAB Policy (Only allow agents to operate within resource boundary)

{
    "name":"organizations/ORGANIZATION_ID/locations/global/principalAccessBoundaryPolicies/example-policy",
    "details": {
    "rules": [
      {
        "description": "Restrict agent identity inside a folder",
        "resources": [
          "//cloudresourcemanager.googleapis.com/folder/0123456789012"
        ],
        "effect": "ALLOW"
      }
    ],
  }
}

// Bind PAB policy to all identities in the organization (incl agent id)

gcloud iam principal-access-boundary-policies bindings create example-pab-binding \
      --organization=organizations/ORGANIZATION_ID \
      --policy=example-policy \ --target-principal-set=cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID

CI/CD 和自动化指南

删除并重新创建代理的自动化部署流水线（例如蓝绿部署、临时测试环境或 Terraform 工作流）可能会遇到静默运行时访问权限丢失。由于每次重新部署都会创建一个具有唯一 ID 的新 reasoningEngines 资源，因此代理会收到一个新的主账号标识符。新主账号不会继承之前授予旧主账号的任何 IAM 权限。

如需在自动化流水线中管理权限，请使用以下策略：

动态检索新的主账号 ID：从部署响应中捕获 spec.effectiveIdentity 值，或在部署后查询 REST API，以获取智能体的活跃身份。在部署后步骤中，将所需的 IAM 绑定应用于此新主账号。

例如，您可以使用以下命令查询具有 gcloud 的活跃身份：

gcloud ai reasoning-engines describe RESOURCE_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --format="value(spec.effectiveIdentity)"

在 Terraform 中，您可以根据已部署的 google_vertex_ai_reasoning_engine 资源 ID 动态构建代理身份主账号，并在 IAM 绑定中引用该主账号：

resource "google_vertex_ai_reasoning_engine" "reasoning_engine" {
  provider = google-beta

  project      = var.project_id
  region       = var.region
  display_name = var.display_name
  description  = var.agent_description

  spec {
    agent_framework = "google-adk"
    identity_type   = "AGENT_IDENTITY"

    source_code_spec {
      inline_source {
        source_archive = filebase64(data.archive_file.agent_tarball.output_path)
      }

      python_spec {
        entrypoint_module = var.agent_python_spec.entrypoint_module
        entrypoint_object = var.agent_python_spec.entrypoint_object
        requirements_file = var.agent_python_spec.requirements_path
        version           = var.agent_python_spec.version
      }
    }

    deployment_spec {
      env {
        name  = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY"
        value = "true"
      }

      env {
        name  = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
        value = "true"
      }
    }
  }
}

locals {
  agent_resource_id        = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1)
  agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}"
}

使用项目级 principalSets 授予基准权限：由于 principalSet 绑定会定位到项目中的所有代理，因此它们在代理删除和重新创建后仍然存在。向项目级 principalSet（而非单个智能体主体）授予常见的非敏感角色（例如服务使用、日志记录和通用模型推理）。限制对高度敏感数据源的单个 principal:// 绑定。

记录 Logging 代理活动

如果您启用 Cloud Logging，则可以查看日志，了解哪些代理和用户访问了 Google Cloud 资源。

当代理代表用户执行操作时，日志会同时显示代理和用户的身份。
当代理根据自己的授权执行操作时，日志仅显示代理的身份。

列出代理及其身份

您可以使用 Google Cloud 控制台和命令行在 Agent Runtime 中查看代理身份列表。

控制台

在 Google Cloud 控制台中，前往 Agent Platform 部署页面。

前往“部署”页面

属于所选项目的已部署代理会显示在列表中。您可以使用过滤条件字段，按指定列过滤列表。
对于每个代理，代理身份都会列在身份列下。

REST API

您可以在使用 REST API 获取 Agent Runtime 实例时检索代理身份。

响应包含以下格式的代理身份：

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

对于不使用代理身份的 Agent Runtime 实例，effectiveIdentity 字段包含与 Agent Runtime 实例关联的服务代理或服务账号名称。

停用情境感知访问权限 (CAA)

默认情况下，尝试在预期 Agent Runtime 运行时之外使用访问令牌会导致以下错误：

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

对于极端情况（例如代理之间的特定令牌共享要求），您可以选择停用默认 CAA 政策。我们强烈不建议执行此操作，因为这会使代理容易受到凭证盗窃。

在创建 Agent Runtime 实例时，通过设置以下环境变量，选择停用默认情境感知访问权限 (CAA) 政策：

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

后续步骤

指南

管理已部署的代理

了解如何管理已部署到 Agent Platform 托管式运行时的智能体。

指南

使用智能体

将智能体与 Agent Platform Runtime 搭配使用。