Cercare agenti, strumenti e skill

Man mano che il tuo ecosistema di agenti cresce, diventa fondamentale trovare l'agente o lo strumento giusto. Agent Registry fornisce funzionalità di ricerca che ti consentono di eseguire ricerche avanzate per parole chiave, prefissi e semantiche tra i tuoi agenti, le loro competenze e i 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 competenze in Agent Registry, registra un agente o un server MCP. Per eseguire queste attività, devi anche avere l'ID progetto per

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 competenze in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Visualizzatore API 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 registro, puoi cercare gli agenti registrati e i server MCP.

La ricerca di agenti corrisponde ai metadati di base, alla descrizione e alle competenze A2A descrittive dichiarate in linea nella scheda dell'agente. La ricerca di server MCP corrisponde alla descrizione e ai loro strumenti deterministici.

Puoi eseguire una ricerca per parole chiave per trovare le risorse che corrispondono a termini specifici nelle loro funzionalità, ad esempio la competenza 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 ricercabili, 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 in grado di 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 fornisce strumenti di 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 per prefisso sono altamente ottimizzate per la latenza, consentendo alle applicazioni di recuperare dinamicamente gli agenti e gli strumenti pertinenti man mano che un utente digita.

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

Ad esempio, cerca gli agenti il cui nome visualizzato inizia con un prefisso specifico, ad esempio 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 competenze autonome

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

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

Modalità di ricerca

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

  • Ricerca per parole chiave: esegue la scansione solo degli attributi dei metadati di base, come il nome visualizzato, la descrizione, il nome (URN) e l'ID competenza. Questa modalità è ottimizzata per le ricerche a bassa latenza, la corrispondenza e il completamento automatico dei nomi. Per un esempio, consulta Cercare le competenze per parole chiave o espressioni.
  • Ricerca semantica: indicizza automaticamente l'intero contenuto del payload SKILL.md, incluse le istruzioni in linguaggio naturale, la struttura del codice e gli asset. Questa modalità corrisponde ai temi concettuali ed è ottimizzata per gli agenti orchestratori che scoprono dinamicamente i bundle di funzionalità pertinenti, in base all'intento. Per un esempio, consulta Cercare le competenze per significato semantico.

Campi di ricerca e sintassi

Quando si esegue la ricerca per metadati o stringhe di parole chiave, vengono indicizzati i seguenti campi:

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

La stringa di query viene collegata ai comandi tramite il --query flag o query parametro e accetta argomenti logici. Puoi utilizzare i seguenti elementi nelle richieste di ricerca:

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

Cercare le competenze per parole chiave o espressioni

L'esempio seguente cerca le competenze che corrispondono a un prefisso del nome visualizzato e a una parola chiave della descrizione specifici:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="displayName:db-* AND description:sql"

Sostituisci quanto segue:

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

Cercare le competenze per significato semantico

L'esempio seguente esegue una ricerca semantica per trovare le competenze correlate alla gestione delle query di database, che corrispondono ai temi concettuali nella query in linguaggio naturale:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="find skills to handle database queries" \
  --search-type=semantic

Sostituisci quanto segue:

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

Competenze pubbliche

Le competenze pubbliche di Google sono rilevabili a livello globale da tutti i progetti. Per un elenco delle competenze pubbliche disponibili, consulta il google/skills repository su GitHub.

Quando esegui una ricerca, Agent Registry riscrive dinamicamente i nomi delle risorse logiche delle competenze pubbliche nell'output in modo che appaiano come se fossero ospitate nel tuo progetto locale per semplificare l'integrazione.