Cercare agenti, strumenti e skill

Man mano che il tuo ecosistema di agenti cresce, trovare l'agente o lo strumento giusto diventa fondamentale. Agent Registry offre funzionalità di ricerca che consentono di eseguire ricerche semantiche, di prefisso e di parole chiave avanzate negli agenti, nelle loro competenze e nei server Model Context Protocol (MCP).

Questo documento spiega come creare query di ricerca per scoprire le funzionalità nel tuo ambiente.

Prima di iniziare

Prima di cercare agenti, strumenti o skill in Agent Registry, registra un agente o un server MCP. Per eseguire queste attività, devi anche disporre dell'ID progetto.

Per utilizzare i comandi gcloud CLI in questo documento, assicurati di aver configurato l'ambiente Google Cloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per cercare agenti, strumenti e skill in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Visualizzatore API di Agent Registry (roles/agentregistry.viewer) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Cercare agenti e strumenti

Per scoprire le funzionalità all'interno del registry, puoi cercare agenti e server MCP registrati.

La ricerca di agenti corrisponde ai relativi metadati di base, alla descrizione e alle skill A2A dichiarate inline nella scheda dell'agente. La ricerca di server MCP corrisponde alla loro descrizione e ai loro strumenti deterministici.

Puoi eseguire una ricerca per parole chiave per trovare risorse che corrispondono a termini specifici nelle loro funzionalità, ad esempio la skill A2A di un agente o lo strumento di un server MCP. Per capire come sono strutturate queste funzionalità nel registro, consulta Schemi JSON. Per un elenco completo dei campi in cui è possibile eseguire ricerche, consulta il riferimento API.

Per eseguire la ricerca per parole chiave, fornisci il flag --search-string. Questo parametro accetta query di testo libero e supporta gli operatori logici: AND, OR e NOT.

Ad esempio, cerca un agente che possa gestire le prenotazioni dei voli:

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

Puoi anche cercare un server MCP in base agli strumenti specifici che offre o alla sua descrizione. Ad esempio, cerca un server MCP che fornisca strumenti per il database:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.

Le ricerche con prefisso sono altamente ottimizzate per la latenza, consentendo alle tue applicazioni di recuperare dinamicamente agenti e strumenti pertinenti mentre un utente digita.

Se stai creando un'interfaccia di orchestratore o una funzionalità di completamento automatico, puoi eseguire ricerche con prefisso in Agent Registry per ottenere risultati che corrispondono all'inizio di una stringa di query. Le ricerche con prefisso utilizzano il simbolo jolly del suffisso (*) per trovare corrispondenze con l'inizio di una parola.

Ad esempio, cerca gli agenti il cui nome visualizzato inizia con un prefisso specifico, come Best_A2A_*:

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

Allo stesso modo, puoi cercare i server MCP il cui nome visualizzato inizia con un prefisso specifico, ad esempio Prod_Server_*:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.

Cercare skill autonome

Puoi cercare skill autonome registrate in Agent Registry. Questa funzionalità ti consente di scoprire funzionalità riutilizzabili da collegare ai tuoi agenti.

Quando cerchi competenze, cerchi la revisione della competenza predefinita. Per aggiornare la revisione predefinita di una skill, consulta Aggiorna i metadati o la revisione predefinita di una skill.

Modalità di ricerca

Puoi utilizzare due modalità di ricerca per le skill in base ai tuoi requisiti:

  • Ricerca per parole chiave:esegue la scansione solo degli attributi dei metadati di base, come nome visualizzato, descrizione, nome (URN) e ID skill. Questa modalità è ottimizzata per ricerche, corrispondenze e completamento automatico dei nomi a bassa latenza. Per un esempio, consulta la sezione Cercare competenze per parola chiave o espressione.
  • Ricerca semantica:indicizza automaticamente i contenuti completi del payload SKILL.md, incluse istruzioni in linguaggio naturale, struttura del codice e asset. Questa modalità corrisponde a temi concettuali ed è ottimizzata per gli agenti orchestratori che scoprono dinamicamente bundle di funzionalità pertinenti, in base alla tua intenzione. Per un esempio, vedi Cercare le competenze in base al significato semantico.

Campi di ricerca e sintassi

Quando esegui la ricerca in base a stringhe di metadati o parole chiave, vengono indicizzati i seguenti campi:

Nome campo Comportamento della richiesta Ricerca per prefisso Ricerca in tutti i campi Descrizione
displayName Senza distinzione tra maiuscole e minuscole Sì Sì Il nome della skill visibile agli utenti. Utilizza questo campo per cercare nomi comuni.
description Senza distinzione tra maiuscole e minuscole No Sì La descrizione dettagliata dello scopo e della funzionalità della skill. Utilizza questo campo per trovare le parole chiave corrispondenti.
name Senza distinzione tra maiuscole e minuscole Sì Sì L'identificatore programmatico della skill. Utilizza questo campo per le corrispondenze nelle stringhe identificatore.
skillId Senza distinzione tra maiuscole e minuscole Sì Sì Il nome della risorsa uniforme (URN) logica della skill. Utilizza questo campo per trovare gli asset di un publisher specifico. Ad esempio, il formato per le skill create da Google è urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher Senza distinzione tra maiuscole e minuscole Sì No L'editore associato alla skill. Utilizza questo campo per filtrare in base all'organizzazione di pubblicazione.
frontmatter.name Senza distinzione tra maiuscole e minuscole No No Il nome della skill definito nel frontmatter del file SKILL.md.
frontmatter.description Senza distinzione tra maiuscole e minuscole No No La descrizione della skill definita nel frontmatter del file SKILL.md.
frontmatter.compatibility Senza distinzione tra maiuscole e minuscole No No La compatibilità della skill definita nel frontmatter del file SKILL.md.
frontmatter.license Senza distinzione tra maiuscole e minuscole No No La licenza della skill definita nel frontmatter del file SKILL.md.
createTime Non applicabile No No Il timestamp di creazione della skill. Questo campo è disponibile solo nei filtri. Supporta gli operatori di intervallo, ad esempio <, > e le corrispondenze esatte.
updateTime Non applicabile No No Timestamp dell'ultimo aggiornamento della skill. Questo campo è disponibile solo nei filtri. Supporta gli operatori di intervallo, ad esempio <, > e le corrispondenze esatte.

Per cercare competenze, fornisci una stringa di query utilizzando il flag --query in gcloud CLI o il parametro searchString nell'API REST. Puoi utilizzare i seguenti elementi di sintassi nelle richieste di ricerca:

  • Operatori booleani:includi gli operatori AND, OR o NOT per concatenare i requisiti.
  • Filtri specifici per campo:hanno come target un campo utilizzando l'operatore :, ad esempio displayName:database.
  • Corrispondenza con prefisso:utilizza il simbolo jolly del suffisso (*) per trovare corrispondenze che iniziano con un prefisso specifico, ad esempio displayName:cloud-*.

Cercare skill per parola chiave o espressione

Ad esempio, cerca le competenze che corrispondono a un prefisso del nome visualizzato e a una parola chiave della descrizione:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registro

Cercare le competenze in base al significato semantico

Ad esempio, trova le competenze relative alla gestione dei database relazionali utilizzando la ricerca semantica:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registro

Abilità pubbliche

Le skill pubbliche fornite da Google sono globali e rilevabili da qualsiasi progetto. Per un elenco delle skill pubbliche disponibili, consulta il repository google/skills su GitHub.

Quando esegui una ricerca, Agent Registry riscrive dinamicamente i nomi delle risorse delle skill pubbliche nell'output in modo che vengano visualizzate ospitate nel tuo progetto locale. Questa procedura semplifica l'integrazione.