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ê pode encontrar 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.

Este guia de início rápido mostra 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 neste documento, configure o ambiente da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para descobrir agentes no Agent Registry, peça ao administrador para conceder a você o papel do IAM de Leitor da API do 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 personalizados papéis ou outros predefinidos papéis.

Listar agentes disponíveis

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

Console

  1. No Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o Google Cloud projeto 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, ambiente de execução e local.

  4. Para conferir 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 cartão 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 do agente:

Console

  1. No Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o Google Cloud projeto 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, ambiente de execução e local.

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

    • Para filtrar por local, clique no menu Local , selecione os locais que você quer filtrar e clique em Aplicar.
    • Para filtrar por ambiente de execução, clique no menu Ambiente de execução , selecione os ambientes de execução 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 os recursos que correspondem a pares de 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, você pode usar displayName='DISPLAY_NAME'. Para filtrar pelo identificador globalmente exclusivo (URN), use agentId='urn:agent:AGENT_URN'.

Conferir detalhes do agente

Se você identificou um agente que quer usar, recupere os metadados completos dele, incluindo o endpoint do ambiente de execução e a lista completa de habilidades:

Console

  1. No Google Cloud console, acesse o Agent Registry:

    Acessar o Agent Registry

  2. No seletor de projetos, selecione o Google Cloud projeto 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, ambiente de execução e local.

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

    A página de detalhes inclui guias para os detalhes do agente.

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

    A disponibilidade dos recursos depende do ambiente de execução. Guias como 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 ambiente de execução. A visão geral também mostra habilidades e o URI do recurso, que são necessários para criar consultas no gráfico de topologia.
    • Observabilidade: insights centrados no aplicativo, como latência, tráfego, erros e gastos com tokens. Essa guia é integrada às ferramentas do Google Cloud Observability para mostrar métricas de desempenho em tempo real e utilização no nível do sistema para ajudar você a gerenciar custos e a experiência do usuário. Para mais informações, consulte a Visão geral da observabilidade.
    • Traces: o caminho exato de uma conversa passo a passo, incluindo a formatação detalhada das mensagens de entrada e do assistente para depurar loops de raciocínio multiagentes complexos ou erros de invocação de ferramentas em tempo real. Para mais informações, consulte Conferir traces de agentes.
    • 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 conformidade. Para mais informações sobre segurança, consulte Conferir descobertas de segurança.
    • Topologia: um mapa visual das relações e fluxos de tráfego entre um agente, o Agent Gateway atribuído a ele 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 a topologia, consulte Conferir gráficos de um agente registrado.
    • Identidade: o principal do agente usado para 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 acompanhamento de interações ativas com o agente.
    • Playground: uma interface de chat direta para testar o comportamento do agente.
    • Memórias: recursos de personalização de longo prazo que geram ou lembram 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. Essa guia permite criar novas tarefas de avaliação, fazer upload de métricas e avaliar o desempenho cognitivo e a confiabilidade do modelo do agente em relação ao tráfego real ou 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 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 habilidades e os metadados somente de saída, como o framework subjacente, a identidade do ambiente de execução e o payload completo do cartão do agente A2A, é possível vincular seu agente com segurança aos fluxos de trabalho do orquestrador usando o Kit de Desenvolvimento de Agente (ADK) ou solicitações de API padrão.

A seguir