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 角色：

如要授予服務專員存取權，請按照下列步驟操作：
- 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
- 安全管理員 (roles/iam.securityAdmin)
建議的代理程式身分角色：
- Agent Context 編輯者 (roles/aiplatform.agentContextEditor)
- 代理人預設存取權 (roles/aiplatform.agentDefaultAccess)
- Vertex AI 使用者 (roles/aiplatform.user)
- 服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)
- 瀏覽器 (roles/browser)
- Storage 物件檢視者 (roles/storage.objectViewer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

授予服務專員存取權

如要讓代理程式存取 Google Cloud 服務，您必須在目標資源上，授予代理程式身分必要的角色。

在 IAM 允許政策中，代理身分會使用主體 ID。

如要授予代理程式資源存取權，請使用 Google Cloud 控制台或 gcloud CLI。

控制台

前往 Google Cloud 控制台的「IAM」頁面，找到要授予存取權的資源。
- 如果是專案，請前往「IAM」頁面：
  前往「IAM」頁面
- 如要查看其他資源，請前往該資源的頁面，然後按一下「權限」或「IAM」分頁標籤。
按一下「授予存取權」。
在「New principals」(新增主體) 欄位中，輸入與要授予的存取層級相符的主體 ID：
- 單一代理程式： 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/*
在「Select a role」(請選擇角色) 欄位中，搜尋並選取要授予的角色。
按一下 [儲存]。

Google Cloud CLI

如要授予代理程式資源存取權，請執行下列指令：

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

更改下列內容：

SERVICE： Google Cloud 服務 (例如 storage 或 bigquery)。
RESOURCE_NAME：資源名稱 (例如 bucket 名稱或資料集 ID)。
PRINCIPAL_IDENTIFIER：與您要授予的存取層級相符的主體 ID：
- 單一代理程式：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 程式碼片段顯示如何手動使用 Agent Identity 憑證，透過 Agent Development Kit (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 管理情境感知存取權政策有助於保護代理程式身分憑證。除了 Agent Gateway 之外，這項政策還會驗證代理程式的存取權杖，強制執行可證明的擁有權 (DPoP)。這項政策也會強制使用 mTLS 存取代理閘道。這可確保憑證繫結權杖只能在預期的受信任執行階段環境 (例如 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]"],
    },
)