共享代理

本页面介绍了如何通过向用户或服务账号授予 Identity and Access Management 权限，在项目中共享单个智能体。

如需共享智能体，请对特定智能体资源授予 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) 智能体）实现自己的身份验证和 授权，则可能会向不受信任的实体公开 。智能体运行时仅提供对智能体界面的粗略访问权限控制。