Registrar um agente personalizado do ADK

O Agent Registry permite registrar agentes personalizados que você cria com o Kit de Desenvolvimento de Agente (ADK) e hospeda na sua própria infraestrutura para que outros desenvolvedores e agentes orquestradores possam descobri-los. Ao expor um card do agente que segue o protocolo Agent2Agent (A2A) e registrar manualmente o endpoint do agente, você torna as habilidades de A2A dele detectáveis no Agent Registry.

Antes de começar

  1. Configure o Agent Registry.

  2. Para uma configuração de projeto único, use o ID do projeto do projeto de governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações de projeto único.

  3. Para usar os comandos da Google Cloud CLI neste documento, configure o ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para registrar agentes personalizados do ADK no Agent Registry, peça ao administrador para conceder a você o papel do IAM de editor da API Agent Registry (roles/agentregistry.editor) no projeto de governança em que o Agent Registry está ativado. 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.

O endpoint do card do agente

Para que o Registro de Agentes possa indexar os recursos do seu agente personalizado, ele precisa expor os metadados e as habilidades de A2A disponíveis usando o protocolo Agent2Agent (A2A).

A especificação A2A exige que os agentes disponibilizem um card do agente, que é um documento JSON que descreve a identidade e as ferramentas do agente, em um endpoint específico, normalmente /.well-known/agent-card.json.

Quando você usa os plug-ins ou módulos de servidor A2A específicos do ADK para registrar seu agente, o framework pode gerar e disponibilizar automaticamente esse card de agente com base na definição de Agent e no tools que você fornece no código.

Registrar o agente exposto

Depois de implantar o agente do ADK no ambiente de hospedagem e ele disponibilizar os endpoints REST, instrua o Agent Registry a descobri-lo.

Como as implantações personalizadas exigem registro manual, você cria um recurso Service no registro. Salve o card de agente gerado como um arquivo JSON local, por exemplo, agent-card.json.

Use a CLI gcloud para registrar o agente com o comando gcloud agent-registry services create, especificando o tipo de especificação a2a-agent-card e fazendo upload do arquivo local usando a flag --agent-spec-content:

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=a2a-agent-card \
    --agent-spec-content=agent-card.json

O tamanho máximo do arquivo de especificação é de 10 KB.

Substitua:

  • AGENT_NAME: o nome que você quer dar ao agente, por exemplo, my-custom-agent.
  • PROJECT_ID: o ID do projeto;
  • LOCATION: o local ou a região do registro.
  • DISPLAY_NAME: o nome legível por humanos do agente.

Depois que o recurso Service é criado, o Agent Registry analisa o card do agente, cria um recurso Agent somente leitura e indexa as habilidades de A2A definidas no seu código Python do ADK para que outros desenvolvedores possam pesquisar por elas.