共用代理

本頁面說明如何將 Identity and Access Management (IAM) 權限授予使用者或服務帳戶，藉此共用專案中的單一代理。

如要共用代理，請授予特定代理資源的 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 = "REASONING_ENGINE_ID"
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

更改下列內容：

  • PROJECT_ID：專案 ID。
  • REGION：區域。
  • REASONING_ENGINE_ID：代理的推論引擎 ID。
  • USER_OR_SA：使用者或服務帳戶。

安全性考量

授予代理存取權後，即可直接傳送訊息至代理的端點。安全控管機制取決於接收代理的程式碼。

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

後續步驟