共享代理

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

如需共享代理，您需要对特定代理资源授予 aiplatform.reasoningEngines.query 权限。

何时共享代理

共享智能体后，多用户或自动化系统便可查询该智能体。共享智能体的常见场景包括：

  • 协作：与团队或组织中的其他成员共享代理，以便他们将其用于自己的任务。
  • 应用集成：向服务账号授予访问权限，以便自定义应用（例如内部聊天机器人或客户支持门户）可以调用智能体来处理特定用户请求。
  • 智能体间通信：在多智能体系统中，一个智能体可能需要调用另一个智能体来获取信息或委派子任务。
  • 信息访问：通过对话式界面为用户提供对数据的受控访问权限，而无需向他们授予对底层数据源的直接访问权限。例如，与所有员工共享连接到知识库（如 HR 政策或技术文档）的智能体。

准备工作

  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.。

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：用户或服务账号。

安全注意事项

授予对代理的访问权限可提供直接访问权限，以便向代理的端点发送消息。安全控制措施由接收代理的代码决定。

  • 可信前端：大多数默认智能体开发套件 (ADK) 智能体都在可信前端中运行。智能体信任前端命令，这使前端能够完全控制会话和用户。在这些情况下，请勿向不受信任的实体授予对智能体的直接访问权限。
  • A2A 智能体：其他智能体（例如 A2A 智能体）如果实现自己的身份验证和授权，则可能会暴露给不受信任的实体。Gemini Enterprise Agent Platform 上的 Agent Runtime 仅提供对智能体界面的粗略访问权限控制。

后续步骤