Pesquisar agentes, ferramentas e habilidades

À medida que seu ecossistema de agentes cresce, encontrar o agente ou a ferramenta certa se torna essencial. O Agent Registry 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 pesquisar 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, configure seu ambiente da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para pesquisar agentes, ferramentas e habilidades 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.

Pesquisar agentes e ferramentas

Para descobrir recursos no seu registro, pesquise agentes e servidores MCP registrados.

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

Você pode fazer uma pesquisa por palavra-chave para encontrar recursos que correspondam a termos específicos em todas as funcionalidades, como a habilidade A2A de um agente ou a ferramenta de um servidor MCP. Para entender como essas funcionalidades são estruturadas 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 é compatível com operadores lógicos: AND, OR e NOT.

Por exemplo, pesquise um agente que possa lidar com 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 ofereç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 conforme um usuário digita.

Se você estiver criando uma interface de orquestrador ou um recurso de preenchimento automático, poderá fazer pesquisas de prefixo no Agent Registry para receber resultados que correspondam ao início de uma string de consulta. As pesquisas por prefixo usam o símbolo 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, você pode pesquisar servidores MCP cujo nome de exibição começa 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 autônomas registradas no Agent Registry. Com esse recurso, você descobre recursos reutilizáveis para anexar aos seus agentes.

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

Modos de pesquisa

Você pode usar dois modos de pesquisa para habilidades com base nos seus requisitos:

  • Pesquisa por palavra-chave:verifica apenas atributos básicos de metadados, como nome de exibição, descrição, nome (URN) e ID da habilidade. Esse modo é otimizado para pesquisas, correspondências e preenchimento automático de nomes de baixa latência. Por exemplo, consulte Pesquisar habilidades por palavra-chave ou expressão.
  • Pesquisa semântica:indexa automaticamente todo o conteúdo 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 orquestradores que descobrem pacotes de recursos relevantes de forma dinâmica, com base na sua intenção. Para ver 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 do caso Pesquisa por prefixo Pesquisa em todos os campos Descrição
displayName Não diferencia maiúsculas e minúsculas Sim Sim O nome da skill que aparece para o usuário. Use este campo para pesquisar nomes comuns.
description Não diferencia maiúsculas e minúsculas Não Sim A descrição detalhada da finalidade e da funcionalidade da habilidade. Use este campo para corresponder palavras-chave.
name Não diferencia maiúsculas e minúsculas Sim Sim O identificador programático da habilidade. Use este campo para correspondências em strings de identificador.
skillId Não diferencia maiúsculas e minúsculas Sim Sim O nome uniforme de recurso (URN) lógico da habilidade. Use este campo para encontrar os recursos de um publisher específico. Por exemplo, o formato das ações criadas pelo Google é urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher Não diferencia maiúsculas e minúsculas Sim Não O editor associado à habilidade. Use este 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. Suporta operadores de intervalo, como <, > e correspondências exatas.
updateTime Não relevante Não Não O carimbo de data/hora da última atualização da habilidade. Esse campo só está disponível em filtros. Suporta operadores de intervalo, como <, > e correspondências exatas.

Para pesquisar habilidades, forneça uma string de consulta usando a flag --query na CLI gcloud ou o parâmetro searchString na API REST. É possível usar os seguintes elementos de sintaxe nas suas solicitações de pesquisa:

  • Operadores booleanos:incluem operadores AND, OR ou NOT para encadear requisitos.
  • Filtros específicos do campo:segmentam um campo usando o operador :, por exemplo, displayName:database.
  • Correspondência de prefixos:use o símbolo de caractere curinga de sufixo (*) para encontrar correspondências que começam com um prefixo específico, por exemplo, displayName:cloud-*.

Pesquisar habilidades por palavra-chave ou expressão

Por exemplo, pesquise habilidades que correspondam a um prefixo de nome de exibição e uma palavra-chave de descrição:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="displayName:cloud-* AND description:database" \
  --search-type=keyword

Substitua:

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

Pesquisar habilidades por significado semântico

Por exemplo, encontre habilidades relacionadas ao gerenciamento de bancos de dados relacionais usando a pesquisa semântica:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="manage and configure relational databases" \
  --search-type=semantic

Substitua:

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

Habilidades públicas

As skills públicas fornecidas pelo Google são globais e podem ser descobertas em qualquer projeto. Para ver uma lista de habilidades públicas disponíveis, consulte o repositório google/skills no GitHub.

Quando você pesquisa, o Agent Registry reescreve dinamicamente os nomes de recursos das habilidades públicas na saída para que elas apareçam hospedadas no seu projeto local. Esse processo simplifica a integração.