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 relacionamentos explícitos 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 especializados.
  • 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 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 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 agênticos.
  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 com 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 

gcloud 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.

Terraform

Para criar uma vinculação entre um agente de origem e um recurso de destino, configure um recurso google_agent_registry_binding. Uma vinculação requer o bloco target:

resource "google_agent_registry_binding" "agent_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Connects a source agent to a target resource."

  source {
    identifier = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }
}

Substitua:

  • REGION: a região do registro.
  • BINDING_NAME: o nome exclusivo que você quer dar à vinculação.
  • DISPLAY_NAME: o nome legível da vinculação.
  • SOURCE_AGENT_NAME: o nome do agente de origem.
  • TARGET_RESOURCE_NAME: o nome do recurso de destino, como um servidor MCP ou endpoint.

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, primeiro crie 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 

gcloud 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.

Terraform

Para configurar uma vinculação de provedor de autenticação no Terraform, especifique o bloco auth_provider_binding com o caminho completo do recurso do provedor de autenticação do conector, além dos escopos e do URI de continuação:

resource "google_agent_registry_binding" "auth_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"

  source {
    identifier = "urn:agent:my-publisher:my-namespace:SOURCE_AGENT_NAME"
  }

  target {
    identifier = "urn:mcp:my-publisher:my-namespace:TARGET_RESOURCE_NAME"
  }

  auth_provider_binding {
    auth_provider = "projects/PROJECT_ID/locations/REGION/connectors/AUTH_PROVIDER_ID"
    scopes        = [SCOPES]
    continue_uri  = "CONTINUE_URI"
  }
}

Substitua:

  • REGION: a região do registro.
  • BINDING_NAME: o nome exclusivo que você quer dar à vinculação.
  • DISPLAY_NAME: o nome legível da vinculação.
  • SOURCE_AGENT_NAME: o nome do agente de origem.
  • TARGET_RESOURCE_NAME: o nome do recurso de destino, como um servidor MCP ou endpoint.
  • PROJECT_ID: o ID do projeto.
  • AUTH_PROVIDER_ID: o ID do provedor de autenticação do conector.
  • SCOPES: uma lista separada por vírgulas de escopos OAuth2, por exemplo, "https://www.googleapis.com/auth/cloud-platform".
  • CONTINUE_URI: o URI de continuação do provedor de autenticação, por exemplo, https://example.com/continue.

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 agent-registry bindings list \
  --project=PROJECT_ID \
  --location=REGION

Ver detalhes da vinculação

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

gcloud 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 

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

Terraform

Para atualizar o nome de exibição ou a descrição de uma vinculação usando o Terraform, modifique o recurso google_agent_registry_binding atual na configuração e execute terraform apply.

Excluir uma vinculação

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

gcloud 

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

Terraform

Remova o recurso google_agent_registry_binding que representa a vinculação da configuração do Terraform e execute terraform apply.

A seguir