Pesquisar agentes, ferramentas e habilidades

À medida que o ecossistema de agentes cresce, encontrar o agente ou a ferramenta certa se torna fundamental. O Registro de Agente oferece recursos de pesquisa que permitem realizar pesquisas avançadas de palavras-chave, prefixos e semânticas em seus agentes, habilidades e servidores do Protocolo de Contexto de Modelo (MCP).

Este documento explica como criar consultas de pesquisa para descobrir recursos no seu ambiente.

Antes de começar

Antes de buscar agentes, ferramentas ou habilidades no Agent Registry, registre um agente ou um servidor MCP. 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 pesquisar agentes, ferramentas e habilidades no Registro de Agente, peça ao administrador para conceder a você o papel do IAM de Leitor da API do Registro de Agente (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 com papéis personalizados ou outros papéis predefinidos.

Pesquisar agentes e ferramentas

Para descobrir recursos no registro, você pode pesquisar agentes registrados e servidores MCP.

A pesquisa de agentes corresponde aos metadados básicos, à descrição e às habilidades A2A descritivas declaradas inline no card de agente. A pesquisa de servidores MCP corresponde à descrição e às suas ferramentas determinísticas.

Você pode realizar uma pesquisa por palavras-chave para encontrar recursos que correspondam a termos específicos em todos os recursos, como a habilidade A2A de um agente ou a ferramenta de um servidor MCP. Para entender como esses recursos são estruturados no registro, consulte Esquemas JSON. Para uma lista completa de campos pesquisáveis, consulte a referência da API.

Para pesquisar por palavras-chave, forneça a flag --search-string. Esse parâmetro aceita consultas de texto livre e oferece suporte a operadores lógicos: AND, OR e NOT.

Por exemplo, pesquise um agente que possa processar reservas de voos:

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="flight OR booking"

Também é possível pesquisar um servidor MCP com base nas ferramentas específicas que ele oferece ou na descrição. Por exemplo, pesquise um servidor MCP que forneça ferramentas de banco de dados:

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="database"

Substitua:

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

As pesquisas de prefixo são altamente otimizadas para latência, permitindo que seus aplicativos recuperem agentes e ferramentas relevantes de forma dinâmica à medida que um usuário digita.

Se você estiver criando uma interface de orquestrador ou um recurso de preenchimento automático, poderá realizar pesquisas de prefixo no Agent Registry para receber resultados que correspondam ao início de uma string de consulta. As pesquisas de prefixo usam o símbolo de caractere curinga de sufixo (*) para corresponder ao início de uma palavra.

Por exemplo, pesquise agentes cujo nome de exibição comece com um prefixo específico, como Best_A2A_*:

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Best_A2A_*"

Da mesma forma, é possível pesquisar servidores MCP cujo nome de exibição comece com um prefixo específico, como Prod_Server_*:

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Prod_Server_*"

Substitua:

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

Pesquisar habilidades independentes

É possível pesquisar habilidades independentes registradas no Registro de Agente. Esse recurso permite descobrir recursos reutilizáveis para anexar aos seus agentes.

Ao pesquisar habilidades, você pesquisa a revisão de habilidade padrão . Para atualizar a revisão padrão de uma habilidade, consulte Atualizar metadados de habilidade ou revisão padrão.

Modos de pesquisa

É possível usar dois modos de pesquisa para habilidades com base nos seus requisitos:

  • Pesquisa por palavras-chave:verifica apenas atributos de metadados básicos, como nome de exibição, descrição, nome (URN) e ID da habilidade. Esse modo é otimizado para pesquisas de baixa latência, correspondência e preenchimento automático de nomes. Para um exemplo, consulte Pesquisar habilidades por palavra-chave ou expressão.
  • Pesquisa semântica:indexa automaticamente o conteúdo completo do payload SKILL.md, incluindo instruções em linguagem natural, estrutura de código e recursos. Esse modo corresponde a temas conceituais e é otimizado para agentes de orquestrador que descobrem pacotes de recursos relevantes de forma dinâmica, com base na sua intenção. Para um exemplo, consulte Pesquisar habilidades por significado semântico.

Campos e sintaxe de pesquisa

Ao pesquisar por metadados ou strings de palavras-chave, os seguintes campos são indexados:

Nome do campo Comportamento de caso Pesquisa de prefixo Pesquisa em todos os campos Descrição
displayName Não diferencia maiúsculas e minúsculas Sim Sim O nome da habilidade voltado ao usuário. Use esse campo para pesquisar nomes comuns.
description Não diferencia maiúsculas e minúsculas Não Sim A descrição detalhada da finalidade e funcionalidade da habilidade. Use esse campo para corresponder a palavras-chave.
name Não diferencia maiúsculas e minúsculas Sim Sim O identificador programático da habilidade. Use esse campo para correspondências em strings de identificadores.
skillId Não diferencia maiúsculas e minúsculas Sim Sim O nome de recurso uniforme (URN) lógico da habilidade. Use esse campo para encontrar os recursos de um publisher específico. Por exemplo, o formato das habilidades criadas pelo Google é urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher Não diferencia maiúsculas e minúsculas Sim Não O publisher associado à habilidade. Use esse campo para filtrar pela organização de publicação.
frontmatter.name Não diferencia maiúsculas e minúsculas Não Não O nome da habilidade definida no frontmatter do arquivo SKILL.md.
frontmatter.description Não diferencia maiúsculas e minúsculas Não Não A descrição da habilidade definida no frontmatter do arquivo SKILL.md.
frontmatter.compatibility Não diferencia maiúsculas e minúsculas Não Não A compatibilidade da habilidade definida no frontmatter do arquivo SKILL.md.
frontmatter.license Não diferencia maiúsculas e minúsculas Não Não A licença da habilidade definida no frontmatter do arquivo SKILL.md.
createTime Não relevante Não Não O carimbo de data/hora em que a habilidade foi criada. Esse campo só está disponível em filtros. Oferece suporte a operadores de intervalo, como <, >, e correspondências exatas.
updateTime Não relevante Não Não O carimbo de data/hora em que a habilidade foi atualizada pela última vez. Esse campo só está disponível em filtros. Oferece suporte a operadores de intervalo, como <, >, e correspondências exatas.

A string de consulta é anexada a comandos pela --query flag ou query parâmetro e aceita argumentos lógicos. É possível usar os seguintes elementos nas solicitações de pesquisa:

  • Operadores booleanos:inclua operadores AND, OR ou NOT para encadear requisitos.
  • Filtros específicos do campo: Direcione um campo usando o operador :, por exemplo, displayName:database.
  • Correspondência de prefixo:use o sufixo curinga :* para encontrar correspondências que comecem com um prefixo específico, por exemplo, skillId:db-*.

Pesquisar habilidades por palavra-chave ou expressão

O exemplo a seguir pesquisa habilidades que correspondam a um prefixo de nome de exibição e uma palavra-chave de descrição específicos:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="displayName:db-* AND description:sql"

Substitua:

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

Pesquisar habilidades por significado semântico

O exemplo a seguir realiza uma pesquisa semântica para encontrar habilidades relacionadas ao processamento de consultas de banco de dados, correspondendo a temas conceituais na consulta de linguagem natural:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="find skills to handle database queries" \
  --search-type=semantic

Substitua:

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

Habilidades públicas

As habilidades públicas do Google podem ser descobertas globalmente em todos os projetos. Para uma lista de habilidades públicas disponíveis, consulte o google/skills repositório no GitHub.

Ao realizar uma pesquisa, o Registro de Agente reescreve dinamicamente os nomes de recursos lógicos de habilidades públicas na saída para que apareçam como se estivessem hospedados no seu projeto local para simplificar a integração.