Pesquisar agentes, ferramentas e habilidades

O Agent Registry permite pesquisar agentes registrados, habilidades de Agent2Agent (A2A), habilidades independentes e servidores do Protocolo de Contexto de Modelo (MCP) por palavra-chave, prefixo ou linguagem natural no console do Google Cloud , na Google Cloud CLI ou na API Agent Registry. As pesquisas por palavra-chave e prefixo ajudam a encontrar rapidamente recursos por nome, identificador ou metadados. A pesquisa semântica encontra recursos conceitualmente relacionados em instruções e descrições em linguagem natural com base na intenção.

As consultas de pesquisa avaliam as descrições de capacidade do agente, do servidor MCP e da habilidade, os esquemas de ferramentas e as instruções de habilidade. Não é possível usar consultas de pesquisa para descobrir endpoints. Para instruções sobre como listar e filtrar endpoints por metadados, consulte Descobrir endpoints e filtrar componentes por metadados.

Antes de começar

1. Configure o Agent Registry.

2. Consiga o ID do projeto para o projeto de governança em que o Agent Registry está ativado.

3. Registrar um agente, um servidor MCP ou uma habilidade no Agent Registry.

4. Para usar os comandos da Google Cloud CLI neste documento, configure o ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para pesquisar agentes, ferramentas e habilidades no Agent Registry, peça ao administrador para conceder a você o papel do IAM de Leitor da API Agent Registry (roles/agentregistry.viewer) no projeto de governança em que o Agent Registry está ativado. 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 no console do Google Cloud , na CLI gcloud ou na API REST.

Ao pesquisar agentes ou servidores MCP, você pode consultar por nome de exibição, descrição ou palavras-chave de capacidade:

• Agentes: as consultas de pesquisa verificam o nome de exibição, a descrição, o identificador e os nomes, descrições e tags das habilidades de A2A inline declaradas no card do agente para encontrar uma correspondência.
• Servidores MCP: as consultas de pesquisa verificam o nome de exibição do servidor, a descrição, o identificador do servidor MCP e os nomes e descrições das ferramentas para encontrar uma correspondência.

Pesquise por palavras-chave

É possível realizar uma pesquisa por palavra-chave para encontrar recursos que contenham termos específicos em todas as funcionalidades, como a habilidade de 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.

As consultas de palavras-chave aceitam strings de texto livre e são compatíveis com os operadores lógicos AND, OR e NOT:

Console

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

   Acessar o Agent Registry

2. No seletor de projetos, selecione o projeto do Google Cloud .

3. Na barra Pesquisar no registro na parte de cima da página, insira uma consulta de palavra-chave com pelo menos três caracteres, como flight ou database, ou um filtro de campo, como Name:booking, e pressione Enter.

   A tabela Resultados da pesquisa mostra os agentes, servidores MCP e habilidades independentes correspondentes nos locais selecionados.

gcloud

Forneça a flag --search-string ao comando gcloud agent-registry agents search ou gcloud agent-registry mcp-servers search.

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"

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 ou global.

REST

Envie uma solicitação POST para o endpoint agents:search ou mcpServers:search com o campo searchString no corpo da solicitação.

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "flight OR booking"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Pesquise um servidor MCP que ofereça ferramentas de banco de dados:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "database"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/mcpServers:search"

Substitua:

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

Pesquisar por prefixo

As pesquisas de prefixo são otimizadas para baixa latência, permitindo que seus aplicativos recuperem agentes e ferramentas relevantes de forma dinâmica enquanto o 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 encontrar resultados que comecem com uma determinada string. As pesquisas de prefixo usam o símbolo curinga de sufixo * para pesquisar o início de uma palavra:

gcloud

Execute o comando gcloud agent-registry agents search ou gcloud agent-registry mcp-servers search com uma expressão de prefixo.

Por exemplo, pesquise agentes com nome de exibição que começa com Best_A2A_*:

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

Da mesma forma, pesquise servidores MCP com nome de exibição que comece com 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 ou global.

REST

Transmita a expressão de prefixo no campo searchString do corpo da solicitação:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "displayName:Best_A2A_*"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Substitua:

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

Pesquisar habilidades independentes

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível pesquisar habilidades independentes registradas no Agent Registry. 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

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

• Pesquisa por palavra-chave: verifica apenas atributos de metadados básicos, como o nome de exibição, a descrição, o nome do recurso e o identificador de habilidade. Esse modo é otimizado para pesquisas de baixa latência, pesquisas exatas e preenchimento automático de nomes. Por exemplo, consulte Pesquisar habilidades por palavra-chave ou expressão.
• Pesquisa semântica: indexa automaticamente todo o conteúdo do payload do SKILL.md, incluindo instruções em linguagem natural, scripts e recursos de metadados. Esse modo identifica temas conceituais e é otimizado para que os agentes de orquestração descubram pacotes de recursos relevantes de forma dinâmica, com base na sua intent. 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 de prefixo	Pesquisa em todos os campos	Descrição
displayName	Não diferencia maiúsculas e minúsculas	Sim	Sim	O nome de exibição da habilidade. 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 pesquisar palavras-chave.
name	Não diferencia maiúsculas e minúsculas	Sim	Sim	O nome do recurso da habilidade. Use este campo para pesquisar pelo nome do recurso.
skillId	Não diferencia maiúsculas e minúsculas	Sim	Sim	O identificador da habilidade. Use esse campo para encontrar os recursos de um editor específico. Por exemplo, o formato das habilidades gerenciadas 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 front matter 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 front matter do arquivo SKILL.md.
frontmatter.compatibility	Não diferencia maiúsculas e minúsculas	Não	Não	A compatibilidade da habilidade definida no front matter 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 front matter 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 está disponível apenas 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 da última atualização da habilidade. Esse campo está disponível apenas em filtros. Oferece suporte a 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 solicitações de pesquisa:

• Operadores booleanos: inclua os operadores AND, OR ou NOT para encadear requisitos.
• Filtros específicos de campo: segmente um campo usando o operador :, por exemplo, displayName:database.
• Pesquisa de prefixo: use o símbolo de caractere curinga de sufixo * para encontrar valores que começam com um prefixo específico, por exemplo, displayName:cloud-*.

Pesquisar habilidades por palavra-chave ou expressão

Pesquisar habilidades que tenham um prefixo de nome de exibição e uma palavra-chave de descrição específicos:

gcloud

Execute o comando gcloud alpha agent-registry skills search com --search-type=keyword:

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 ou global.

REST

Envie uma solicitação GET para o endpoint skills:search com searchString e searchType=KEYWORD:

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=displayName:cloud-* AND description:database" \
    --data-urlencode "searchType=KEYWORD" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Substitua:

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

Pesquisar habilidades por significado semântico

Encontre habilidades relacionadas ao gerenciamento de bancos de dados relacionais usando a pesquisa semântica:

gcloud

Execute o comando gcloud alpha agent-registry skills search com --search-type=semantic:

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 ou global.

REST

Envie uma solicitação GET para o endpoint skills:search com searchString e searchType=SEMANTIC:

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=manage and configure relational databases" \
    --data-urlencode "searchType=SEMANTIC" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Substitua:

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

Habilidades gerenciadas pelo Google

As habilidades gerenciadas pelo Google podem ser encontradas em qualquer projeto. Para ver uma lista de habilidades gerenciadas pelo Google disponíveis, consulte o repositório google/skills no GitHub.

Descobrir endpoints e filtrar componentes por metadados

Também é possível descobrir qualquer componente no Agent Registry, incluindo endpoints registrados, listando a coleção e filtrando os campos de metadados estruturados:

• Descobrir endpoints: como os recursos Endpoint não são compatíveis com consultas :search, você os descobre navegando na guia Endpoints no console doGoogle Cloud , executando gcloud agent-registry endpoints list --filter ou chamando o método REST endpoints.list. Para instruções completas, consulte Gerenciar e descobrir endpoints.
• Filtrar agentes, servidores MCP e habilidades: quando você souber o identificador de registro (URN), o nome de exibição ou o atributo de um componente, filtre a coleção no console doGoogle Cloud ou transmita --filter para gcloud agent-registry agents list, gcloud agent-registry mcp-servers list ou gcloud alpha agent-registry skills list. Para mais detalhes, consulte Gerenciar agentes, Gerenciar servidores e ferramentas MCP e Gerenciar habilidades.