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 de vários agentes 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 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 fazer a autenticação 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 as vinculações, faça o seguinte:

  1. Configure o Agent Registry.
  2. Registre os componentes de origem e destino. Para mais informações, consulte Registrar componentes de agentes.
  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 Fazer a autenticação em ferramentas e recursos.
  4. Para usar os comandos da Google Cloud CLI neste documento, verifique se você tem o ambiente da CLI gcloud configurado.

Funções exigidas

Para ter 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 personalizados papéis ou outros predefinidos papéis.

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 de recurso uniforme (URN, na sigla em inglês).
  • 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, é necessário criar o provedor de autenticação com o gerenciador de autenticação de identidade do agente. Para mais informações, consulte Fazer a autenticação em 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 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 Kit de Desenvolvimento de Agentes (ADK).

Listar vinculações

Liste 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