Compartilhar um agente

Nesta página, descrevemos como compartilhar um único agente no seu projeto concedendo permissões do Identity and Access Management 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. Os cenários comuns para compartilhar um agente incluem o seguinte:

  • Colaboração: compartilhe um agente com outros membros da sua equipe ou organização para usá-lo nas tarefas deles.
  • 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 agente 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 uma função personalizada 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 no 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 = google_vertex_ai_reasoning_engine.my_engine.name
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.
  • USER_OR_SA: o usuário ou a conta de serviço.

Considerações sobre segurança

A concessão de acesso ao agente fornece acesso direto para enviar mensagens ao endpoint FastAPI do agente. As garantias de segurança são determinadas pelo código do agente receptor.

  • Front-end confiável: a maioria dos agentes padrão do ADK opera em um front-end confiável. O agente confia nos comandos de 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 ambiente de execução do agente fornece apenas controle de acesso bruto à interface do agente.