Compartilhar um agente

Nesta página, descrevemos como compartilhar um único agente no seu projeto concedendo permissões do Identity and Access Management (IAM) a usuários ou contas de serviço.

Para compartilhar um agente, conceda a permissão aiplatform.reasoningEngines.query no recurso de agente específico.

Quando compartilhar um agente

Ao compartilhar um agente, vários usuários ou sistemas automatizados podem fazer consultas nele. Os cenários comuns para compartilhar um agente incluem:

  • Colaboração: compartilhe um agente com outros membros da sua equipe ou organização para que eles o usem nas tarefas.
  • Application Integration: conceda acesso a uma conta de serviço para que um aplicativo personalizado, como um chatbot interno ou um portal de suporte ao cliente, possa chamar o agente para processar solicitações específicas do usuário.
  • Comunicação entre agentes: em um sistema multiagente, um agente pode precisar chamar outro para receber informações ou delegar uma subtarefa.
  • Acesso a informações: forneça aos usuários acesso controlado aos dados por uma interface de conversação sem conceder acesso direto às fontes de dados subjacentes. Por exemplo, compartilhe um agente conectado a uma base de conhecimento (como políticas de RH ou documentação técnica) com todos os funcionários.

Antes de começar

  1. Identifique o agente que você quer compartilhar. Você precisa do ID do projeto e do ID do mecanismo de raciocínio do agente.
  2. Identifique os usuários ou as contas de serviço a que você quer conceder acesso.

Etapa 1: criar uma função personalizada

Para seguir o princípio de privilégio mínimo, crie um papel personalizado que contenha apenas a permissão aiplatform.reasoningEngines.query.

gcloud

Para criar um papel personalizado no projeto, execute o seguinte comando:

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

Como alternativa, para criar o papel para toda a organização:

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

Substitua:

  • ROLE_ID: o ID do papel, como agentUser.
  • ROLE_TITLE: um título para o papel, como Agent Runtime user.
  • ROLE_DESCRIPTION: uma breve descrição do papel, como Allows querying agents.
  • PROJECT_ID: o ID do projeto.
  • ORGANIZATION_ID: o ID da organização.

Terraform

Para criar o papel personalizado usando o Terraform, use o recurso 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"]
}

Substitua:

  • ROLE_ID: o ID do papel, como agentUser.
  • ROLE_TITLE: um título para o papel, como Agent Runtime user.
  • PROJECT_ID: o ID do projeto.

O nome do papel personalizado será projects/PROJECT_ID/roles/ROLE_ID ou organizations/ORGANIZATION_ID/roles/ROLE_ID.

Etapa 2: conceder o papel no agente

Depois que o papel for criado, vincule-o a um agente e especifique o usuário ou a conta de serviço a que você quer conceder permissão.

Python

Para conceder o papel usando Python, use a biblioteca 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})

Substitua:

  • LOCATION: a região em que o agente está implantado, como us-central1.
  • PROJECT_ID: o ID do projeto.
  • REASONING_ENGINE_ID: o ID do mecanismo de raciocínio do agente.
  • ROLE_ID: o ID do papel, como agentUser.
  • USER_OR_SA: o e-mail do usuário ou a conta de serviço, como user:someone@example.com ou serviceAccount:my-sa@my-project.iam.gserviceaccount.com.

Terraform

Para conceder o papel usando o Terraform, use o recurso 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"
}

Substitua:

  • PROJECT_ID: o ID do projeto.
  • REGION: a região.
  • REASONING_ENGINE_ID: o ID do mecanismo de raciocínio do agente.
  • USER_OR_SA: o usuário ou a conta de serviço.

Considerações sobre segurança

Conceder acesso ao agente permite enviar mensagens diretamente para o endpoint dele. Os controles de segurança são determinados pelo código do agente receptor.

  • Front-end confiável: a maioria dos agentes padrão do Kit de Desenvolvimento de Agente (ADK) opera em um front-end confiável. O agente confia nos comandos do front-end, o que dá ao front-end controle total das sessões e dos usuários. Nesses casos, não conceda acesso direto ao agente para entidades não confiáveis.
  • Agentes A2A: outros agentes, como os agentes Agent2Agent (A2A), podem ser expostos a entidades não confiáveis se implementarem a própria autenticação e autorização. O Agent Runtime na Gemini Enterprise Agent Platform oferece apenas controle de acesso geral à interface do agente.

A seguir