Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

搭配 Agent Runtime 使用代理身分

在 Agent Runtime 使用 Agent Identity，可為每個代理提供安全的身分，並以最小權限原則管理存取權管理。本文說明如何建立具有代理身分的代理、授權存取Google Cloud API，以及管理第三方服務的憑證。

總覽

代理身分會為每個代理提供身分，採用最小權限原則，並與代理的生命週期連結，因此代理身分是比服務帳戶更安全的安全主體。現有的 IAM 存取權管理控制項支援代理身分，可強化管理。

根據預設，代理身分憑證會透過 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 bucket 的舊版 bucket 角色 (storage.legacyBucketReader、storage.legacyBucketWriter 或 storage.legacyBucketOwner)。

建立具有代理身分的代理

建立 Agent Runtime 執行個體時，您可以為部署至 Agent Runtime 的代理佈建專屬身分。這個身分會繫結至 Agent Runtime 的代理資源 ID，且與您用來開發代理的代理架構無關。

建立代理身分時，您可以選擇下列選項：

建立 Agent Runtime 執行個體，但不部署代理程式碼：如要在部署代理前設定 IAM 政策，可以建立代理身分，但不部署代理程式碼。方法是建立 Agent Runtime 執行個體，並只指定 identity_type 欄位：
```
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 執行個體：如要在部署代理程式碼時佈建代理身分，請使用 Agent Platform SDK for Python 和 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 bucket 的名稱。

使用 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 執行個體時，系統會提供唯讀、經系統認證的代理身分 (主體 ID)：

# 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/serviceusage.serviceUsageConsumer：授予代理權限，允許使用專案配額和 Agent Platform SDK。
roles/browser：授予基本 Google Cloud 功能的存取權。
roles/secretmanager.secretAccessor：授予代理程式 Secret Manager 中 Secret 的存取權。如果將 Secret 參照為環境變數，也必須將 roles/secretmanager.secretAccessor 授予 Agent Platform 服務代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com)，以便在部署期間擷取 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：所在區域。請參閱執行階段支援的地區。
AGENT_ENGINE_ID：Agent Runtime 執行個體的資源 ID。
ROLE_NAME 是要授予的角色名稱。例如：roles/vision.user。如需預先定義的角色清單，請參閱「瞭解角色」。

設定 IAM 後，Agent Platform SDK 的應用程式預設憑證會自動使用代理身分，向Google Cloud 資源執行驗證。

授予 Agent2Agent (A2A) 委派存取權

設計多代理系統時，如果上層代理會叫用在代理登錄資料庫中註冊的遠端子代理，上層代理的身分必須具備權限，才能在代理登錄資料庫中探索子代理，並叫用其端點。

為確保上層代理的身分具備必要權限，可探索及叫用遠端子代理，請要求管理員將下列 IAM 角色授予上層代理的身分：

讓上層代理在執行階段查詢子代理的端點：上層專案或登錄檔資源的 Agent Registry API 檢視者 (roles/agentregistry.viewer)
允許上層代理傳送訊息給子代理：目標子代理推論引擎資源的 Agent Platform 使用者 (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。

授予多位代理存取權

您可以將 IAM 角色授予特定專案或整個組織中的所有 Agent Runtime 代理。

如要將角色授予專案中的所有 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/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"

授予代理對代理 (A2A) 呼叫的存取權

如果代理 (代理 A) 需要叫用其他代理 (代理 B)，請勿授予專案層級權限，請改為授予僅含 aiplatform.reasoningEngines.query 和 aiplatform.reasoningEngines.get 的自訂角色，並繫結至代理 B 的資源路徑。

建立自訂角色 agentInvoker，並授予必要權限：

gcloud iam roles create agentInvoker --project=PROJECT_ID \
  --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \
  --stage=GA

將自訂角色繫結至代理 B 的資源，授予代理 A 身分的存取權：

gcloud beta ai reasoning-engines add-iam-policy-binding AGENT_B_ID \
  --region=LOCATION \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_A_ID" \
  --role="projects/PROJECT_ID/roles/agentInvoker"

為避免代理身分對其他代理執行機密管理作業，請為 reasoningEngines.create、.delete 和 .update 建立 IAM 拒絕政策：

deniedPrincipals:
  - principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
deniedPermissions:
  - aiplatform.googleapis.com/reasoningEngines.create
  - aiplatform.googleapis.com/reasoningEngines.delete
  - aiplatform.googleapis.com/reasoningEngines.update

拒絕代理存取

如要拒絕代理存取資源，可以使用 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"
      ]
    }
  }
]
}

設定主體存取邊界，限制代理可存取的資源，即使代理可能具備其他權限也一樣：

// 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 資源，因此代理會收到新的主體 ID。先前授予前一個主體的任何 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:// 繫結至高度機密的資料來源。

記錄代理活動

如果啟用 Cloud Logging，您就能查看記錄，瞭解哪些代理和使用者存取了 Google Cloud 資源。

如果代理代表使用者執行動作，記錄會同時顯示代理和使用者的身分。
如果代理是依據自身授權執行，記錄只會顯示代理的身分。

列出代理及其身分

您可以使用 Google Cloud 控制台和指令列，在 Agent Runtime 查看代理身分清單。

控制台

前往 Google Cloud 控制台的「Agent Platform Deployments」(Agent Platform 部署作業) 頁面。

前往「Deployments」(部署作業) 頁面

清單會顯示已部署的代理，這些代理屬於所選專案。您可以使用「Filter」(篩選器) 欄位，依指定資料欄篩選清單。
每個代理的身分都會列在「Identity」(身分) 欄下方。

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 使用代理。