Gerenciar vinculações

No Agent Registry, uma vinculação representa uma conexão entre um agente de origem e um recurso de destino, como outro agente, um servidor MCP ou um endpoint. Ao criar vinculações, você estabelece relações explícitas que permitem que os agentes do orquestrador interajam com recursos downstream.

Você usa vinculações para lidar com dois cenários:

  • Conexões de recursos:é possível vincular um agente de origem a um recurso de destino, como outro agente, um servidor MCP ou um endpoint. Esse cenário permite mapear fluxos de trabalho multiagente em que um orquestrador principal delega tarefas a subagentes ou ferramentas especializadas.
  • Permissões delegadas:é possível associar um agente a um provedor de autenticação para permitir que ele se conecte a destinos externos ou ferramentas personalizadas usando as próprias credenciais ou em nome de um usuário individual. Essa vinculação é necessária se o agente precisar se autenticar em servidores ou ferramentas MCP remotos usando tokens OAuth ou chaves de API. Com as vinculações, não é necessário definir manualmente os provedores de autenticação no código. Para instruções detalhadas, consulte Criar uma vinculação de provedor de autenticação neste documento.

Este documento descreve como criar, visualizar, atualizar e excluir vinculações no Agent Registry.

Antes de começar

Antes de gerenciar vinculações, faça o seguinte:

  1. Configurar o Agent Registry.
  2. Registre os recursos de origem e destino. Para mais informações, consulte Registrar serviços.
  3. Se você quiser configurar vinculações para permissões delegadas, crie um provedor de autenticação com o gerenciador de autenticação de identidade do agente. Para mais informações, consulte Autenticar ferramentas e recursos.
  4. Para usar os comandos da CLI gcloud neste documento, verifique se você configurou seu ambiente da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para gerenciar vinculações no Agent Registry, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar uma vinculação

Crie uma vinculação para conectar um agente de origem a um recurso de destino:

gcloud alpha agent-registry bindings create BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --source-identifier="SOURCE_ID" \
  --target-identifier="TARGET_ID"

Substitua:

  • BINDING_NAME: o nome que você quer dar à vinculação, por exemplo, my-custom-binding.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região do registro.
  • DISPLAY_NAME: o nome legível que você quer dar à vinculação, por exemplo, My Custom Binding.
  • SOURCE_ID: o identificador do agente de origem no formato de nome uniforme de recurso (URN).
  • TARGET_ID: o identificador do recurso de destino no formato URN, como um identificador de servidor MCP.

Criar uma vinculação de provedor de autenticação

É possível associar um agente a um provedor de autenticação para permissões delegadas. Antes de criar essa vinculação, crie o provedor de autenticação com o gerenciador de autenticação de identidade do agente. Para mais informações, consulte Autenticar ferramentas e recursos.

Ao especificar o nome do recurso --auth-provider, use o ID do projeto:

gcloud alpha agent-registry bindings create BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --source-identifier="SOURCE_ID" \
  --auth-provider="projects/PROJECT_ID/locations/REGION/connectors/AUTH_PROVIDER_ID"

Substitua AUTH_PROVIDER_ID pelo ID do seu provedor de autenticação.

Para exemplos de como usar essas vinculações no código do agente, consulte Resolver vinculações no código do ADK.

Listar vinculações

Listar todas as vinculações em um local específico:

gcloud alpha agent-registry bindings list \
  --project=PROJECT_ID \
  --location=REGION

Ver detalhes da vinculação

Recupere os detalhes de uma única vinculação:

gcloud alpha agent-registry bindings describe BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION

Atualizar uma vinculação

Atualize os parâmetros de uma vinculação atual, como o nome de exibição ou a descrição, usando flags da CLI gcloud:

gcloud alpha agent-registry bindings update BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="NEW_DISPLAY_NAME"

Excluir uma vinculação

Para remover uma conexão entre recursos, exclua o registro de vinculação:

gcloud alpha agent-registry bindings delete BINDING_NAME \
  --project=PROJECT_ID \
  --location=REGION

A seguir