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

搭配 Agent Runtime 使用代理身分

在 Agent Runtime 上使用代理程式身分，可提供安全的代理程式專屬身分，進而採用最低權限原則來管理存取權。本文說明如何建立具有代理程式身分的代理程式、授權存取Google Cloud API，以及管理第三方服務的憑證。

總覽

代理身分提供每個代理的身分，可採用最低權限做法，並與代理的生命週期相關聯，因此代理身分比服務帳戶更安全。透過 IAM 支援代理人身分，現有的存取權管理控制項可啟用嚴格的控管機制。

根據預設，系統會透過 Google 管理的情境感知存取權 (CAA) 政策，保護代理程式身分憑證。這項政策會強制執行 mTLS 繫結，確保代理程式的憑證 (以憑證繫結權杖的形式) 只能在預期的受信任執行階段環境 (例如 Cloud Run 容器) 中使用。這項安全基準可防止遭竊的憑證遭到重播，防範憑證竊取和帳戶盜用 (ATO)。

本頁面涵蓋下列主題：

建立具有代理身分的代理：建立代理，以便在部署至 Agent Runtime 時，代理會自動收到專屬身分。
使用代理身分授權存取 API Google Cloud ：使用已佈建的代理身分，授予或拒絕代理人存取 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 政策，可以建立代理程式身分，但不部署代理程式碼。如要這麼做，請建立 Agent Runtime 執行個體，但只填寫 identity_type 欄位：
```
import vertexai
from vertexai import agent_engines
from vertexai import types

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.create(
  config={"identity_type": types.IdentityType.AGENT_IDENTITY}
)
```
使用代理身分建立 Agent Runtime 執行個體後，您可以使用 agent_engine.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 vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Agent Platform 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
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "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 部署代理，並設定代理身分：使用 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.project-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 功能存取權。

如果您使用記錄、指標和 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" \

更改下列內容：

ORGANIZATION_ID：貴機構的 ID。
PROJECT_NUMBER：您的專案編號。
LOCATION：您的區域。請參閱支援的執行階段區域。
AGENT_ENGINE_ID：Agent Runtime 執行個體的資源 ID。
ROLE_NAME 是要授予的角色名稱。例如：roles/vision.user。如需預先定義角色清單，請參閱「瞭解角色」一文。

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

授予多位代理人存取權

您可以將 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.project-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"
      ]
    }
  }
]
}

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

// 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

記錄代理程式活動

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

如果服務專員代表使用者執行動作，記錄檔會同時顯示服務專員和使用者的身分。
如果代理程式是自行採取行動，記錄檔只會顯示代理程式的身分。

列出代理程式及其身分

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

控制台

前往 Google Cloud 控制台的 Agent Platform「Deployments」頁面。

前往「Deployments」(部署作業)

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

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 政策。強烈建議您不要這麼做，因為這會導致代理程式容易遭到憑證竊取。

如要停用預設的情境感知存取權 (CAA) 政策，請在建立 Agent Runtime 執行個體時，設定下列環境變數：

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

後續步驟

指南

管理已部署的代理程式

瞭解如何管理已部署至 Agent Platform 代管執行階段的代理程式。

指南

使用代理

使用 Agent Platform Runtime 執行代理程式。