共用代理

本頁說明如何將身分與存取權管理權限授予使用者或服務帳戶，藉此共用專案中的單一代理程式。

如要共用代理程式，請授予特定代理程式資源的 aiplatform.reasoningEngines.query 權限。

共用代理程式的時機

分享代理程式後，多位使用者或自動化系統就能查詢代理程式。分享代理程式的常見情況包括：

  • 協作：與團隊或機構的其他成員共用代理，讓他們將代理用於自己的工作。
  • 應用程式整合：授予服務帳戶存取權，讓自訂應用程式 (例如內部聊天機器人或客戶支援入口網站) 呼叫代理程式，處理特定使用者要求。
  • 代理對代理溝通：在多代理系統中，一個代理可能需要呼叫另一個代理來取得資訊或委派子工作。
  • 資訊存取：透過對話式介面控管使用者存取資料的權限，不必授予他們基礎資料來源的直接存取權。舉例來說，與所有員工共用連結至知識庫 (例如人資政策或技術文件) 的代理。

事前準備

  1. 找出要共用的代理程式。您需要專案 ID 和代理程式的推理引擎 ID。
  2. 找出要授予存取權的使用者或服務帳戶。

步驟 1：建立自訂角色

如要遵循最小權限原則，請建立只包含 aiplatform.reasoningEngines.query 權限的自訂角色。

gcloud

如要在專案中建立自訂角色，請執行下列指令：

gcloud iam roles create ROLE_ID  --project=PROJECT_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

如要為整個機構建立角色，請按照下列步驟操作：

gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

更改下列內容：

  • ROLE_ID：角色 ID，例如 agentUser。
  • ROLE_TITLE：角色的名稱，例如 Agent runtime user。
  • ROLE_DESCRIPTION：角色的簡短說明，例如 Allows querying agents。
  • PROJECT_ID：專案 ID。
  • ORGANIZATION_ID：組織 ID。

Terraform

如要使用 Terraform 建立自訂角色，請使用 google_project_iam_custom_role 資源：

resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id     = "ROLE_ID"
title       = "ROLE_TITLE"
project     = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}

更改下列內容：

  • ROLE_ID：角色 ID，例如 agentUser。
  • ROLE_TITLE：角色的名稱，例如 Agent runtime user。
  • PROJECT_ID：專案 ID。

自訂角色名稱會是 projects/PROJECT_ID/roles/ROLE_ID 或 organizations/ORGANIZATION_ID/roles/ROLE_ID。

步驟 2：授予代理的角色

建立角色後，請將角色繫結至代理程式，並指定要授予權限的使用者或服務帳戶。

Python

如要使用 Python 授予角色，請使用 google-cloud-aiplatform 程式庫：

from google.cloud.aiplatform_v1 import ReasoningEngineServiceClient
from google.api_core.client_options import ClientOptions

# Initialize the client
client = ReasoningEngineServiceClient(
  client_options=ClientOptions(api_endpoint="LOCATION-aiplatform.googleapis.com")
)

# Define the resource path
resource = "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

# Get the current IAM policy and add the new binding
policy = client.get_iam_policy(request={"resource": resource})
binding = policy.bindings.add()
binding.role = "projects/PROJECT_ID/roles/ROLE_ID"
binding.members.append("USER_OR_SA")

# Update the IAM policy on the resource
client.set_iam_policy(request={"resource": resource, "policy": policy})

更改下列內容：

  • LOCATION：部署代理程式的區域，例如 us-central1。
  • PROJECT_ID：專案 ID。
  • REASONING_ENGINE_ID：代理程式的推論引擎 ID。
  • ROLE_ID：角色 ID，例如 agentUser。
  • USER_OR_SA：使用者電子郵件地址或服務帳戶，例如 user:someone@example.com 或 serviceAccount:my-sa@my-project.iam.gserviceaccount.com。

Terraform

如要使用 Terraform 授予角色，請使用 google_vertex_ai_reasoning_engine_iam_member 資源：

resource "google_vertex_ai_reasoning_engine_iam_member" "example" {
project          = "PROJECT_ID"
region           = "REGION"
reasoning_engine = google_vertex_ai_reasoning_engine.my_engine.name
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

更改下列內容：

  • PROJECT_ID：專案 ID。
  • REGION：區域。
  • USER_OR_SA：使用者或服務帳戶。

安全性考量

授予代理程式存取權後，即可直接存取代理程式的 FastAPI 端點，並傳送訊息。安全保障取決於接收代理程式的程式碼。

  • 可信任的前端：大多數預設 ADK 代理都從可信任的前端運作。代理程式信任前端指令，因此前端可完全控管工作階段和使用者。在這些情況下，請勿將代理程式的直接存取權授予不受信任的實體。
  • A2A 代理：如果其他代理 (例如 Agent2Agent (A2A) 代理) 實作自己的驗證和授權，可能會暴露給不受信任的實體。代理執行階段只會對代理介面提供粗略的存取控管。