使用代理程式本身的 ID 向 Google Cloud 進行驗證

代理可使用自己的身分存取 Google Cloud API 和其他資源。Google 建議在 Google Cloud其他服務 Google Cloud 上代管的代理使用此方法。

代理程式自行採取行動時，會使用主要 SPIFFE 身分要求存取權杖。 Google Cloud

事前準備

  1. 確認您選擇的驗證方法正確無誤。
  2. 建立及部署代理，並啟用 Agent Identity。
  3. 確認您具備完成這項工作所需的角色。

必要的角色

如要取得授予代理程式 Google Cloud 服務存取權所需的權限，請要求管理員在目標資源中授予下列 IAM 角色：

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

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

授予代理存取權

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

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

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

控制台

  1. 前往 Google Cloud 控制台的「IAM」頁面，為要授予存取權的資源設定權限。
    • 如要查看專案的政策，請前往「IAM」(身分與存取權管理) 頁面：

      前往「IAM」頁面

    • 如要查看其他資源，請前往該資源的頁面，然後按一下「權限」或「IAM」分頁標籤。
  2. 按一下 「授予存取權」。
  3. 在「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/*
  4. 在「Select a role」(選取角色) 欄位中，搜尋並選取要授予的角色。
  5. 按一下 [儲存]。

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 用戶端程式庫會自動使用 Agent Identity。

下列 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 Identity 憑證。除了 Agent Gateway 之外，這項政策還會驗證代理的存取權杖，強制執行「擁有權證明」(DPoP)。這項政策也要求使用相互傳輸層安全性 (mTLS) 存取 Agent Gateway。這項規定可確保繫結憑證的權杖只能在預期的受信任執行階段環境 (例如 Cloud Run 容器) 中使用。這項安全基準可讓遭竊的憑證無法重播，有助於防範憑證遭竊和帳戶入侵 (ATO)。

在極少數情況下 (例如代理程式之間有特定的權杖共用需求)，如果您需要直接在標頭中插入權杖，或是代理程式無法透過 401 UNAUTHENTICATED 錯誤進行驗證，可以選擇停用預設的情境感知存取權政策。選擇停用後，權杖繫結保護機制就會移除，這些短期存取權杖容易遭到竊取或重播攻擊。因此不建議停用這項功能。

如要停用這項功能，請在部署代理時設定下列環境變數：

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

部署代理

將代理部署至 Google Cloud時，請務必啟用 Agent Identity。如要部署至 Gemini Enterprise Agent Platform 的 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]"],
    },
)

後續步驟