Guia de início rápido: descobrir um agente

A descoberta é o mecanismo principal para acelerar o desenvolvimento com cargas de trabalho agênticas. Ao pesquisar no Agent Registry, você encontra agentes com as habilidades necessárias, como um "Agente de política corporativa" ou um "Agente de reserva de voos", em vez de criar integrações duplicadas do zero.

Neste guia de início rápido, mostramos como descobrir agentes registrados no Agent Registry.

Antes de começar

Antes de começar este guia de início rápido, registre um agente no Agent Registry. Você também precisa do ID do projeto para realizar essas tarefas.

Para usar os comandos da CLI gcloud Cloud neste documento, verifique se você configurou seu ambiente da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para descobrir agentes no Registro de agentes, peça ao administrador para conceder a você o papel do IAM de Leitor da API Agent Registry (roles/agentregistry.viewer) 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.

Listar agentes disponíveis

Confira uma lista completa de todos os agentes registrados e indexados no registro:

Console

  1. No console do Google Cloud , acesse Registro de agentes:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o projeto Google Cloud em que você configurou o Agent Registry.

  3. Selecione a guia Agentes.

    A página mostra uma lista de todos os agentes registrados e os detalhes deles, como nome, identificador, descrição, tempo de execução e local.

  4. Para ver todos os detalhes de um agente, clique no nome dele.

gcloud

Para listar todos os agentes em um local específico, use o comando agents list:

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

Substitua:

  • PROJECT_ID: o ID do projeto.
  • REGION: a região do registro.

A resposta tem a aparência do exemplo a seguir.

- name: projects/1234567890/locations/us-central1/agents/my-travel-agent
  displayName: Travel Orchestrator Agent
  description: 'Decomposes natural language travel requests into sub-tasks.'
  version: 1.0.0
  protocols:
    - type: A2A_AGENT
      protocolVersion: "0.3"
      interfaces:
        - url: https://api.example.com/.well-known/agent-card.json
          protocolBinding: HTTP_JSON
  attributes:
    agentregistry.googleapis.com/system/Framework:
      framework: "google-adk"
    agentregistry.googleapis.com/system/RuntimeIdentity:
      identity: "principal://..."
  card:
    type: A2A_AGENT_CARD
    content: {...}

O campo card contém todo o conteúdo do card do agente A2A, quando disponível.

Filtrar agentes registrados

Se você tiver vários agentes ou quiser confirmar o registro de um agente específico, filtre a lista pelos metadados dele:

Console

  1. No console do Google Cloud , acesse Registro de agentes:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o projeto Google Cloud em que você configurou o Agent Registry.

  3. Selecione a guia Agentes.

    A página mostra uma lista de todos os agentes registrados e os detalhes deles, como nome, identificador, descrição, tempo de execução e local.

  4. Filtre a lista pelo local do agente ou pelo recurso de tempo de execução dele:

    • Para filtrar por local, clique no menu Local, selecione os locais que você quer filtrar e clique em Aplicar.
    • Para filtrar por tempo de execução, clique no menu Tempo de execução, selecione os tempos que você quer filtrar e clique em Aplicar.

    A página mostra uma lista filtrada dos agentes registrados para as condições selecionadas.

gcloud

Filtre a lista de agentes para retornar apenas recursos que correspondam a pares chave-valor específicos usando a flag --filter:

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Substitua:

  • PROJECT_ID: o ID do projeto.
  • REGION: a região do registro.
  • FILTER_EXPRESSION: a expressão de filtro para os agentes que você quer filtrar. Por exemplo, para filtrar por nome de exibição, use displayName='DISPLAY_NAME'. Para filtrar pelo identificador (URN) globalmente exclusivo, use agentId='urn:agent:AGENT_URN'.

Conferir detalhes do agente

Se você identificou um agente que quer usar, é possível recuperar os metadados completos dele, incluindo o endpoint de tempo de execução e a lista completa de habilidades:

Console

  1. No console do Google Cloud , acesse Registro de agentes:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o projeto Google Cloud em que você configurou o Agent Registry.

  3. Selecione a guia Agentes.

    A página mostra uma lista de todos os agentes registrados e os detalhes deles, como nome, identificador, descrição, tempo de execução e local.

  4. Clique no nome do agente que você quer ver.

    A página de detalhes inclui guias com informações sobre o agente.

  5. Clique na guia correspondente para ver detalhes específicos do agente.

    A disponibilidade do recurso depende do seu tempo de execução. As guias Sessões, Playground, Memórias e Avaliação são recursos específicos que aparecem para agentes criados em ambientes de execução gerenciados, como o Vertex AI Agent Engine:

    • Visão geral: detalhes principais do agente, incluindo nome, identificador, local, descrição e tempo de execução. A visão geral também mostra as habilidades e o URI do recurso, que são necessários para criar consultas no gráfico de topologia.
    • Observabilidade: insights centrados em aplicativos, como latência, tráfego, erros e gastos com tokens. Essa guia se integra às ferramentas do Google Cloud Observability para mostrar métricas de desempenho em tempo real e a utilização no nível do sistema, ajudando você a gerenciar custos e a experiência do usuário. Para mais informações, consulte a Visão geral da observabilidade.
    • Rastreamentos: o caminho exato de uma conversa etapa por etapa, incluindo formatação detalhada de mensagens do usuário e do assistente para depurar loops de raciocínio multiagente complexos ou erros de invocação de ferramentas em tempo real. Para mais informações, consulte Visualizar traces do agente.
    • Segurança: descobertas do Model Armor e do Security Command Center, incluindo violações da política de conteúdo, riscos de vazamento de dados e avaliações de compliance. Para mais informações sobre segurança, consulte Ver descobertas de segurança.
    • Topologia: um mapa visual das relações e fluxos de tráfego entre um agente, o gateway de agente atribuído e os servidores MCP com que ele interage. Para mais informações sobre o Agent Gateway, consulte a Visão geral do Agent Gateway. Para mais informações sobre topologia, consulte Ver gráficos de um agente registrado.
    • Identidade: o principal do agente usado para a aplicação da política. Você usa essa identidade, por exemplo, para configurar vinculações de provedor de autenticação para autenticação em ferramentas e recursos.
    • Sessões: histórico de conversas persistente e rastreamento de interações ativas com o agente.
    • Playground: uma interface de chat direto para testar o comportamento do agente.
    • Memórias: recursos de personalização de longo prazo que geram ou recuperam detalhes de conversas anteriores com o agente para preservar o contexto em todas as interações.
    • Avaliação: detalhes de todas as tarefas de avaliação do agente. Nela, é possível criar novas tarefas de avaliação, fazer upload de métricas e avaliar a performance cognitiva e a confiabilidade do modelo do agente em relação ao tráfego real ou a simulações sintéticas.

gcloud

Para conferir os metadados detalhados de um agente específico, use o comando agents describe:

gcloud alpha agent-registry agents describe AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Substitua:

  • AGENT_NAME: o nome do seu agente, por exemplo, my-travel-agent.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região do registro.

Com o endpoint do agente, as definições de habilidade e os metadados somente de saída, como o framework subjacente, a identidade de tempo de execução e a carga útil completa do card do agente A2A, é possível vincular com segurança o agente aos fluxos de trabalho do orquestrador usando o Kit de Desenvolvimento de Agente (ADK) ou solicitações de API padrão.

A seguir