O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar agentes

Para gerenciar sua frota de agentes de maneira eficaz, é necessário manter o registro preciso. Para isso, confira e atualize os detalhes dos agentes à medida que seu ecossistema de IA evolui, substitua metadados ou remova agentes que não estão mais em uso.

Neste documento, explicamos como visualizar e modificar os detalhes e a configuração dos agentes registrados.

Antes de começar

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

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

Funções exigidas

Para receber as permissões necessárias para gerenciar agentes registrados no Registro de agentes, 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 papéis personalizados ou outros papéis predefinidos.

Descobrir agentes disponíveis

Depois de registrar agentes, é possível descobri-los no seu ambiente e conferir as configurações detalhadas, como endpoints, habilidades e metadados associados.

Listar e visualizar todos os agentes

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

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.

A página mostra uma lista de todos os agentes registrados. A lista inclui o nome, o identificador, o tipo, a descrição, a versão, o tempo de execução e o local do agente.
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 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 dele:

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.

A página mostra uma lista de todos os agentes registrados. A lista inclui o nome, o identificador, o tipo, a descrição, a versão, o tempo de execução e o local do agente.
Filtre a lista pela localização do agente ou pelo recurso de tempo 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 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 metadados específicos usando a flag --filter:

gcloud 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 (URN) globalmente exclusivo, use agentId='urn:agent:AGENT_URN'.

Terraform

Para recuperar um agente registrado específico filtrando os metadados dele, configure a fonte de dados google_agent_registry_agent com o argumento filter:

data "google_agent_registry_agent" "filtered_agent" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

Substitua:

REGION: a região do registro.
DISPLAY_NAME: o nome legível por humanos do agente para filtrar, por exemplo, Support Agent.

Conferir detalhes de um agente

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

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.

A página mostra uma lista de todos os agentes registrados. A lista inclui o nome, o identificador, o tipo, a descrição, a versão, o tempo de execução e o local do agente.
Clique no nome do agente que você quer visualizar.

A página de detalhes inclui guias com informações sobre o agente.
Clique na guia correspondente para ver os detalhes específicos do agente.

A disponibilidade dos recursos 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 Agent Runtime na Gemini Enterprise Agent Platform:
- 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 de A2A e a referência de tempo de execução, que são necessárias para criar consultas no gráfico de topologia.
- Observabilidade: insights centrados em aplicativos, como latência, tráfego, erros e gasto de tokens. Essa guia se integra às ferramentas do Google Cloud Observability para mostrar métricas de performance 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 Ver rastreamentos 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 Gateway de Agente, consulte a visão geral do Gateway de Agente. 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 direta para testar o comportamento do agente.
- Memórias: recursos de personalização de longo prazo que geram ou relembram 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 simulações sintéticas.

gcloud

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

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

Substitua AGENT_NAME pelo nome do seu agente, por exemplo, my-custom-agent.

Terraform

Para recuperar detalhes sobre um agente registrado específico usando o ID dele, configure a fonte de dados google_agent_registry_agent:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  agent_id = "AGENT_ID"
}

output "agent_create_time" {
  description = "The timestamp when the agent was registered."
  value       = data.google_agent_registry_agent.my_agent.create_time
}

output "agent_update_time" {
  description = "The timestamp when the agent was last updated."
  value       = data.google_agent_registry_agent.my_agent.update_time
}

Substitua:

REGION: a região do registro.
AGENT_ID: o identificador exclusivo do seu agente, por exemplo, my-custom-agent.

Atualizar metadados e endpoints do agente

Se o URL de tempo de execução do seu 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.

Console

Atualize os detalhes do agente disponíveis no console Google Cloud :

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.

A página mostra uma lista de todos os agentes registrados. A lista inclui o nome, o identificador, o tipo, a descrição, a versão, o tempo de execução e o local do agente.
Clique no nome do agente que você quer atualizar.
Na guia Visão geral do agente, clique em Editar.
No painel Editar serviço, insira as informações atualizadas do agente, como o novo nome ou a descrição.
Clique em Salvar.

gcloud

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

Atualize o nome de exibição e a descrição: use as flags --display-name e --description. Por exemplo:
```
gcloud 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 seu agente, por exemplo, my-support-agent.
- PROJECT_ID: o ID do projeto.
- REGION: a região do registro.
Atualize o URL do endpoint: use a flag --interfaces para especificar o novo endpoint, por exemplo:
```
gcloud agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
```
Substitua:
- ENDPOINT_URL: o novo URL do Agent Endpoint, 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.
Atualize a especificação do agente: use as flags --agent-spec-type e --agent-spec-content, por exemplo, se você tiver um novo cartão do agente:
```
gcloud agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@AGENT_SPEC_FILE
```
Substitua AGENT_SPEC_FILE pelo caminho para o novo arquivo de especificação do agente, por exemplo, new-agent-card.json. Observe o prefixo @ necessário ao transmitir o caminho para --agent-spec-content. O tamanho máximo do arquivo de especificação é de 10 KB.

Terraform

Para atualizar os metadados, o URL do endpoint ou a especificação do agente registrado, modifique os parâmetros do recurso google_agent_registry_service atual na sua configuração e execute terraform apply:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "New Display Name"
  description  = "Updated description of the agent's purpose."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

Substitua:

REGION: a região do registro.
AGENT_NAME: o nome exclusivo que você quer dar ao agente, por exemplo, my-support-agent.
ENDPOINT_URL: o URL do endpoint de API do agente. Por exemplo, https://api.remote-service.com/v1/agents/1234.
PROTOCOL: a vinculação de protocolo para o endpoint. Os valores válidos são HTTP_JSON, GRPC ou JSONRPC.

Remover um agente

Para excluir agentes que foram registrados automaticamente no Agent Registry, você precisa excluir o agente subjacente no tempo de execução específico do Google Cloud . O agente é removido automaticamente do registro.

Para remover um agente registrado manualmente do registro, exclua o recurso Service subjacente. Essa ação remove o agente dos resultados da pesquisa e o torna indescobrível para outras ferramentas:

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.

A página mostra uma lista de todos os agentes registrados. A lista inclui o nome, o identificador, o tipo, a descrição, a versão, o tempo de execução e o local do agente.
Clique no nome do agente que você quer remover.
Na guia Visão geral do agente, clique em Excluir.
Na caixa de diálogo de confirmação, digite EXCLUIR para confirmar a ação.
Clique em Excluir.

gcloud

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

Terraform

Remova o recurso google_agent_registry_service que representa o agente da configuração do Terraform e execute terraform apply.

A seguir

Saiba como ver as relações entre agentes usando um gráfico de topologia.
Saiba como pesquisar agentes e ferramentas usando consultas de linguagem natural.

Gerenciar agentes Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Descobrir agentes disponíveis

Listar e visualizar todos os agentes

Console

gcloud

Filtrar agentes registrados

Console

gcloud

Terraform

Conferir detalhes de um agente

Console

gcloud

Terraform

Atualizar metadados e endpoints do agente

Console

gcloud

Terraform

Remover um agente

Console

gcloud

Terraform

A seguir

Gerenciar agentes