Pesquisar agentes, ferramentas e habilidades

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

  1. Configure o Agent Registry.
  2. 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.

  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 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:

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:

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.

É 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

  1. No console do Google Cloud , acesse Registro de agentes:

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

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

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: ou urn:mcp:googleapis.com:.
  • Componentes com escopo de projeto: use urn:agent:projects- ou urn: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 ou urn: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 como us-central1, uma multirregião como us ou eu ou global.
  • 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 ou urn: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 como us-central1, uma multirregião como us ou eu ou global.

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 como us-central1, uma multirregião como us ou eu ou global. 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 Service registrados 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 Service registrados manualmente e os recursos do Binding criados 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, 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 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 ou global.

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

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

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 como us-central1, uma multirregião como us ou eu ou global.

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 Endpoint não são compatíveis com consultas de pesquisa, 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ê 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 --filter nos comandos gcloud agent-registry agents list, gcloud agent-registry mcp-servers list ou gcloud agent-registry skills list. Por exemplo, inclua --filter='protocols.type="A2A_AGENT"' no comando gcloud agent-registry agents list para mostrar apenas agentes A2A e execute gcloud agent-registry agents describe para ver o card de agente completo e os endpoints protocols de um agente. Para mais detalhes, consulte Gerenciar agentes, Gerenciar servidores e ferramentas MCP e Gerenciar habilidades.