Gerenciar agentes

O gerenciamento eficaz da sua frota de agentes exige que você mantenha o registro preciso, visualizando e atualizando os detalhes do serviço à medida que suas cargas de trabalho evoluem, substituindo metadados ou removendo agentes que não estão mais em uso.

Este documento detalha como visualizar e modificar os detalhes e a configuração do agente registrado.

Antes de começar

Antes de gerenciar agentes, verifique se seus agentes estão registrados no Agent Registry. Você também precisa do ID do projeto para realizar essas tarefas.

Para usar os comandos da CLI gcloud neste documento, verifique se você tem configurado o ambiente da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para gerenciar agentes registrados 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. 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.

Descobrir agentes disponíveis

Depois de registrar os agentes, você pode descobri-los no seu ambiente e conferir as configurações detalhadas, como endpoints, habilidades e metadados associados.

Listar e visualizar agentes

É possível listar todos os agentes registrados no seu ambiente e conferir as configurações detalhadas, como endpoints, habilidades e metadados associados:

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. A lista inclui o nome, o identificador, tipo, a descrição, a versão, o ambiente de execução e o local do agente.

  4. Para conferir todos os detalhes de um agente, clique no nome do agente.

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.

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. A lista inclui o nome, o identificador, tipo, a descrição, a versão, o ambiente de execução e o local do agente.

  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 recursos que correspondam a metadados específicos, usando a flag --filter:

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

Substitua FILTER_EXPRESSION pela expressão de filtro dos agentes que você quer filtrar. Por exemplo, você pode usar os seguintes filtros:

  • Para filtrar por nome de exibição, use displayName='DISPLAY_NAME'.
  • Para pesquisar pelo identificador globalmente exclusivo (URN), use agentId='urn:agent:AGENT_URN'.

Conferir detalhes de um agente

Confira os detalhes de um agente específico, incluindo protocolos, habilidades e identidade:

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. A lista inclui o nome, o identificador, tipo, a descrição, a versão, o ambiente de execução e o local do agente.

  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 do recurso depende do seu 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 se integra às ferramentas de 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 multiagente 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 gateway de agente atribuído e os servidores MCP com que ele interage. Para mais informações sobre o gateway de agente, consulte a Visão geral do gateway de agente. Para mais informações sobre 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 pelo nome do agente, por exemplo, my-custom-agent.

Atualizar metadados e endpoints do agente

Se o URL do ambiente de execução do agente mudar ou se você quiser substituir o nome de exibição, a descrição ou a especificação, atualize os metadados do agente.

Para a API Agent Registry, os recursos Agent são usados para descoberta. Portanto, é necessário atualizar o recurso Service registrado diretamente.

Use a Google Cloud CLI com flags específicas para modificar os parâmetros do agente:

  • Atualizar o nome de exibição e a descrição: use as flags --display-name e --description, por exemplo:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="New display name" \
  --description="Updated description of the agent's purpose."

    Substitua:

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

  • Atualizar o URL do endpoint: use a flag --interfaces para especificar o novo endpoint, por exemplo:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

    Substitua:

    • ENDPOINT_URL: o novo URL do endpoint do serviço do agente, por exemplo, https://new-api.example.com/agent.
    • PROTOCOL: a vinculação de protocolo para o endpoint. Os valores válidos são HTTP_JSON, GRPC ou JSONRPC.

  • Atualizar a especificação do agente: use a flag --agent-spec-content, por exemplo, se você tiver um novo cartão de agente:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --agent-spec-content=@AGENT_SPEC

    Substitua AGENT_SPEC pelo nome da nova especificação do agente, por exemplo, new-agent-card.json.

Remover um agente

Para excluir agentes que foram registrados automaticamente no Agent Registry, é necessário excluir o agente subjacente no ambiente de execução específico. Google Cloud O agente é removido automaticamente do registro.

Para remover um agente registrado manualmente do registro, é necessário excluir o recurso Service subjacente. Essa ação remove o agente dos resultados da pesquisa e o torna indetectável para outras ferramentas:

gcloud alpha agent-registry services delete AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Substitua:

  • AGENT_NAME: o nome do agente que você quer remover, por exemplo, my-support-agent.
  • PROJECT_ID: o ID do projeto.
  • REGION: a região do registro.

A seguir