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

O compartilhamento de um agente permite que vários usuários ou sistemas automatizados consultem o agente. Confira alguns cenários comuns para compartilhar um agente:

  • Colaboração: compartilhe um agente com outros membros da equipe ou organização para que eles o usem nas tarefas.
  • Integração de aplicativos: conceda acesso a uma conta de serviço para que um aplicativo personalizado, como um chatbot interno ou um portal de atendimento 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 obter informações ou delegar uma subtarefa.
  • Acesso a informações: ofereça aos usuários acesso controlado a dados por meio de uma interface conversacional 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 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 uma função personalizada 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 a função 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 da função, como agentUser.
  • ROLE_TITLE: um título para a função, como Agent Runtime user.
  • ROLE_DESCRIPTION: uma breve descrição da função, como Allows querying agents.
  • PROJECT_ID: o ID do projeto.
  • ORGANIZATION_ID: o ID da organização.

Terraform

Para criar a função personalizada 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 da função, como agentUser.
  • ROLE_TITLE: um título para a função, como Agent Runtime user.
  • PROJECT_ID: o ID do projeto.

O nome da função personalizada será projects/PROJECT_ID/roles/ROLE_ID ou organizations/ORGANIZATION_ID/roles/ROLE_ID.

Etapa 2: conceder a função ao agente

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

Python

Para conceder a função usando o 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 da função, 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 a função 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 oferece acesso direto para enviar mensagens ao endpoint do agente. Os controles de segurança são determinados pelo código do agente receptor.

  • Front-end confiável: a maioria dos agentes do Kit de Desenvolvimento de Agente (ADK) padrão opera em um front-end confiável. O agente confia nos comandos do front-end, o que dá ao front-end controle total de sessões e usuários. Nesses casos, não conceda acesso direto ao agente a 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 oferece apenas controle de acesso bruto à interface do agente.

A seguir