O Registro de Agente 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. É possível fazer pesquisas no console do Google Cloud , na Google Cloud CLI ou na API Agent Registry. As pesquisas por palavra-chave e prefixo ajudam a encontrar recursos por nome, identificador ou metadados. A pesquisa semântica encontra recursos conceitualmente relacionados em instruções e descrições de linguagem natural com base na intenção.
As consultas de pesquisa avaliam as descrições de recursos do agente, do servidor MCP e das habilidades, os esquemas de ferramentas e as instruções de habilidades. Não é possível usar consultas de pesquisa para descobrir endpoints. Para listar e filtrar endpoints por metadados, consulte Descobrir endpoints e filtrar componentes por metadados.
Antes de começar
- Configure o Agent Registry.
Para uma configuração de projeto único, use o ID do projeto da governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações em um único projeto.
Registrar um agente, um servidor MCP ou uma habilidade no Agent Registry.
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 Registro de Agentes, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto de governança em que o Registro de Agentes está ativado:
-
Pesquisar agentes, ferramentas e habilidades:
Leitor da API Agent Registry (
roles/agentregistry.viewer) -
Pesquisar e visualizar habilidades independentes:
Usuário do Agent Registry (
roles/agentregistry.user)
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 Agent Registry.
Dependendo do tipo de componente, é possível pesquisar pelos seguintes campos:
- Agentes: pesquise pelo nome, descrição ou identificador do agente. Também é possível pesquisar por nomes, descrições, tags e exemplos de comandos das habilidades de A2A inline no Card do agente.
- Servidores MCP: pesquise pelo nome, pela descrição ou pelo identificador do servidor MCP. Também é possível pesquisar pelos nomes e descrições das ferramentas do servidor MCP.
Para encontrar agentes integrados do Google, servidores MCP remotos do Google e do Google Cloud ou componentes com escopo de projeto por prefixo de origem, consulte Encontrar componentes por prefixo de origem. Para encontrar por tipo de protocolo ou inspecionar o arquivo JSON completo do Card do Agente, filtre por metadados.
Campos de pesquisa
Quando você pesquisa por palavra-chave, o Agent Registry verifica todos os
campos indexados no recurso de descoberta do componente agêntico, incluindo
habilidades inline de A2A em agentes e nomes e descrições de ferramentas em servidores MCP. Para
restringir a pesquisa a um campo específico, use o operador :, por exemplo,
skills.tags:incident:
| Filtro de campo | Componente agêntico | Pesquisa de prefixo aceita | Descrição |
|---|---|---|---|
displayName |
Agentes e servidores MCP | Sim | Nome de exibição do agente ou servidor MCP. |
name |
Agentes e servidores MCP | Sim | Nome do recurso do agente ou servidor MCP. |
agentId |
Agentes | Sim |
URN do identificador
do agente (também aceita correspondências exatas com =).
|
mcpServerId |
Servidores MCP | Não |
URN do identificador do servidor MCP (também aceita correspondências exatas com =).
|
description |
Agentes | Não | É a descrição do agente. |
skills |
Agentes | Não | Pesquisa em todos os campos de habilidades A2A inline extraídos do card do agente. |
skills.id, skills.name,
skills.description, skills.tags,
skills.examples |
Agentes | Não | Segmenta um campo de habilidade A2A inline específico extraído do card do agente. |
Os campos personalizados no cartão do agente e no transporte protocols não são indexados para
pesquisa. Em vez disso, é possível inspecionar essas informações usando filtros para metadados
ao listar ou descrever agentes. Para mais informações, consulte
Descobrir endpoints e filtrar componentes por metadados.
Pesquise por palavras-chave
É possível realizar uma pesquisa por palavra-chave para encontrar recursos que contenham termos específicos em todas as habilidades, 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.
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
No console do Google Cloud , acesse Registro de agentes:
No seletor de projetos, selecione o projeto do Google Cloud .
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
flightoudatabase, ou um filtro de campo, comoName:booking, e pressioneEnter.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 agente pelas tags de habilidade A2A ou pelos comandos de exemplo:
gcloud agent-registry agents search \ --project=PROJECT_ID \ --location=REGION \ --search-string='skills.tags:incident OR skills.examples:"rollout"'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 ouglobal.
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 ouglobal.
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 de caractere 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 comece 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 começa 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 ouglobal.
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 ouglobal.
Encontrar componentes por prefixo de origem
Cada agente e servidor MCP inclui um prefixo de origem no identificador de registro:
- Agentes integrados do Google e servidores MCP remotos do Google e do Google Cloud : use
urn:agent:googleapis.com:ouurn:mcp:googleapis.com:. - Componentes com escopo de projeto: use
urn:agent:projects-ouurn:mcp:projects-, seguido pelo número do projeto, por exemplo,urn:agent:projects-PROJECT_NUMBER:.
Por exemplo, é possível pesquisar por esses prefixos de origem para encontrar apenas agentes integrados do Google, todos os agentes com escopo de projeto ou agentes de um projeto específico:
gcloud
Inclua um prefixo de origem na flag --search-string do comando gcloud agent-registry agents search. Use o campo agentId para pesquisar por identificador de agente:
Agentes integrados do Google: incluem o prefixo
urn:agent:googleapis.com:*:gcloud agent-registry agents search \ --project=PROJECT_ID \ --location=REGION \ --search-string='agentId:"urn:agent:googleapis.com:*"'Agentes com escopo de projeto: use
urn:agent:projects-*para corresponder a todos os agentes com escopo de projeto ouurn:agent:projects-PROJECT_NUMBER:*para segmentar um projeto específico:Pesquise todos os agentes com escopo de projeto:
gcloud agent-registry agents search \ --project=PROJECT_ID \ --location=REGION \ --search-string='agentId:"urn:agent:projects-*"'Pesquise agentes em um projeto específico:
gcloud agent-registry agents search \ --project=PROJECT_ID \ --location=REGION \ --search-string='agentId:"urn:agent:projects-PROJECT_NUMBER:*"'
Substitua:
PROJECT_ID: o ID do projeto;REGION: o local do registro, como uma região comous-central1, uma multirregião comousoueuouglobal.PROJECT_NUMBER: o número do projeto para os agentes de um projeto específico.
REST
Envie uma solicitação POST para o endpoint agents:search com um prefixo agentId em searchString:
Agentes integrados do Google: incluem o prefixo
urn:agent:googleapis.com:*:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"searchString": "agentId:\"urn:agent:googleapis.com:*\""}' \ "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"Agentes com escopo de projeto: use
urn:agent:projects-*para corresponder a todos os agentes com escopo de projeto ouurn:agent:projects-PROJECT_NUMBER:*para segmentar um projeto específico:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"searchString": "agentId:\"urn:agent:projects-*\""}' \ "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"
Substitua:
PROJECT_ID: o ID do projeto;REGION: o local do registro, como uma região comous-central1, uma multirregião comousoueuouglobal.
Também é possível filtrar agentes registrados e filtrar servidores MCP registrados por prefixo de origem ao listá-los em um projeto específico.
Pesquisar em um limite de gerenciamento
Se você configurou um limite de gerenciamento, é possível pesquisar todos os agentes e servidores MCP em um local em todos os projetos membros nesse limite no seu projeto de gerenciamento:
gcloud agent-registry agents search \
--project=MANAGEMENT_PROJECT_ID \
--location=LOCATION \
--search-string="analytics"
Para restringir os resultados da pesquisa no projeto de gerenciamento aos agentes em um projeto de membro específico, filtre pelo número desse projeto de membro usando o identificador do agente na flag --search-string:
gcloud agent-registry agents search \
--project=MANAGEMENT_PROJECT_ID \
--location=LOCATION \
--search-string='agentId:"urn:agent:projects-MEMBER_PROJECT_NUMBER:*"'
Substitua:
MANAGEMENT_PROJECT_ID: o ID do projeto de gerenciamento. Para pesquisar exclusivamente em um único projeto membro sem rollup entre projetos, especifique o ID desse projeto membro na flag--project.LOCATION: o local para pesquisar no limite de gerenciamento, como uma região comous-central1, uma multirregião comousoueuouglobal. O Agent Registry agrega recursos nesse mesmo local no projeto de gerenciamento e em todos os projetos membros no limite.MEMBER_PROJECT_NUMBER: o número do projeto membro.
É possível filtrar servidores MCP por projeto membro usando o identificador de servidor MCP ao listar servidores MCP. Para mais informações, consulte Filtrar servidores MCP registrados.
Quando você pesquisa no projeto de gerenciamento:
- Recursos agregados descobertos automaticamente: o Agent Registry pesquisa agentes e servidores MCP descobertos automaticamente no local especificado em todos os projetos membros no limite de gerenciamento, além de todos os recursos
Serviceregistrados criados nesse local no projeto de gerenciamento. - Nomes de recursos com escopo de solicitação: nos resultados da pesquisa, cada nome de recurso de um agente ou servidor MCP retornado usa o projeto especificado no URL da solicitação e preserva o ID que o Agent Registry atribuiu quando o componente foi registrado. O identificador do registro mantém o projeto de membro.
- Recursos registrados com escopo de projeto: os recursos do
Serviceregistrados manualmente e os recursos doBindingcriados em um projeto membro permanecem com escopo definido para esse projeto membro e não aparecem nos resultados da pesquisa do projeto de gerenciamento. Para que eles fiquem visíveis além do limite de gerenciamento, crie-os no projeto de gerenciamento.
Pesquisar habilidades independentes
É 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.
O Agent Registry filtra os resultados da pesquisa de habilidades com base nas suas permissões do Identity and Access Management (IAM). Uma solicitação de pesquisa retorna apenas as habilidades
para as quais você tem a permissão agentregistry.skills.get, seja concedida no
nível do projeto ou por uma
política do IAM no nível do recurso na habilidade.
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 nome de exibição, descrição, nome do recurso e 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 agentes de orquestração que descobrem 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. |
frontmatter.allowed_tools |
Não diferencia maiúsculas e minúsculas | Não | Não | As ferramentas permitidas da habilidade definida no front matter do arquivo SKILL.md. |
frontmatter.metadata.KEY |
Não diferencia maiúsculas e minúsculas | Não | Não | Uma entrada de chave-valor de metadados personalizados definida em metadata no front matter do arquivo SKILL.md. Aceita o operador : em consultas de pesquisa e correspondências exatas (= e !=) em filtros. |
state |
Não diferencia maiúsculas e minúsculas | Não | Não | O estado do ciclo de vida atual da habilidade, como ACTIVE, DRAFT, DISABLED, DEPRECATED ou DECOMMISSIONED. Esse campo está disponível apenas em filtros e é compatível com correspondências exatas (= e !=). |
targetState |
Não diferencia maiúsculas e minúsculas | Não | Não | O estado do ciclo de vida de destino da habilidade, como ACTIVE, DRAFT, DISABLED, DEPRECATED ou DECOMMISSIONED. Esse campo está disponível apenas em filtros e é compatível com correspondências exatas (= e !=). |
defaultRevisionFindingCount |
Não relevante | Não | Não | O número de descobertas de segurança detectadas na revisão padrão da habilidade. Esse campo só está disponível em filtros e é compatível com correspondências exatas (= e !=) e operadores de intervalo (<, <=, > e >=), como defaultRevisionFindingCount = 0 ou defaultRevisionFindingCount > 0. |
createTime |
Não relevante | Não | Não | O carimbo de data/hora em que a habilidade foi criada. Este 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. Este 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 campo searchString no corpo da solicitação da
API REST. É possível usar os seguintes elementos de sintaxe nas solicitações de pesquisa:
- Operadores booleanos: inclua os operadores
AND,ORouNOTpara 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 agent-registry skills search com --search-type=keyword:
gcloud 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 ouglobal.
REST
Envie uma solicitação POST ao endpoint
skills:search
com os campos searchString e searchType no corpo da solicitação:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"searchString": "displayName:cloud-* AND description:database",
"searchType": "KEYWORD"
}' \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/skills:search"
Substitua:
PROJECT_ID: o ID do projeto;REGION: a região do registro ouglobal.
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 agent-registry skills search com --search-type=semantic:
gcloud 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 ouglobal.
REST
Envie uma solicitação POST ao endpoint
skills:search
com os campos searchString e searchType no corpo da solicitação:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"searchString": "manage and configure relational databases",
"searchType": "SEMANTIC"
}' \
"https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/skills:search"
Substitua:
PROJECT_ID: o ID do projeto;REGION: a região do registro ouglobal.
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.
Para pesquisar habilidades de um editor verificado e gerenciado pelo Google, filtre no campo publisher:
gcloud agent-registry skills search \
--project=PROJECT_ID \
--location=REGION \
--query="publisher:cloud.google.com" \
--search-type=keyword
Substitua:
PROJECT_ID: o ID do projeto;REGION: o local do registro, como uma região comous-central1, uma multirregião comousoueuouglobal.
Descobrir endpoints e filtrar componentes por metadados
Também é possível descobrir qualquer componente no Registro de Agentes, incluindo endpoints registrados, listando a coleção correspondente e filtrando os campos de metadados estruturados:
- Descobrir endpoints: como os recursos do
Endpointnão são compatíveis com consultas de pesquisa, você os descobre navegando na guia Endpoints no console doGoogle Cloud , executandogcloud agent-registry endpoints list --filterou chamando o método RESTendpoints.list. Para instruções completas, consulte Gerenciar e descobrir endpoints. - Filtrar agentes, servidores MCP e habilidades: quando você sabe o identificador de registro (URN), o nome de exibição, o tipo de protocolo ou o atributo de um componente, é possível filtrar a lista no console do Google Cloud ou incluir a flag
--filternos comandosgcloud agent-registry agents list,gcloud agent-registry mcp-servers listougcloud agent-registry skills list. Por exemplo, inclua--filter='protocols.type="A2A_AGENT"'no comandogcloud agent-registry agents listpara mostrar apenas agentes A2A e executegcloud agent-registry agents describepara ver o card de agente completo e os endpointsprotocolsde um agente. Para mais detalhes, consulte Gerenciar agentes, Gerenciar servidores e ferramentas MCP e Gerenciar habilidades.