Guida rapida: scopri un agente

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

La scoperta è il meccanismo principale per accelerare lo sviluppo con i carichi di lavoro agentici. Se esegui una ricerca all'interno di Agent Registry, puoi trovare agenti esistenti con le competenze di cui hai bisogno, ad esempio un "Agente per le norme aziendali" o un "Agente per la prenotazione di voli" esistenti, anziché creare integrazioni duplicate da zero.

Questa guida rapida mostra come scoprire gli agenti registrati in Agent Registry.

Prima di iniziare

Prima di iniziare questa guida rapida, registra un agente in Agent Registry. 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 scoprire gli agenti 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.

Elenco degli agenti disponibili

Visualizza un elenco completo di tutti gli agenti registrati e indicizzati nel registry:

Console

1. Nella console Google Cloud , vai a Registro agenti:

   Vai al registry degli agenti

2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

3. Seleziona la scheda Agenti.

   La pagina mostra un elenco di tutti gli agenti registrati e i relativi dettagli, ad esempio nome, identificatore, descrizione, runtime e posizione.

4. Per visualizzare i dettagli completi di un agente, fai clic sul suo nome.

gcloud

Per elencare tutti gli agenti in una posizione specifica, utilizza il comando agents list:

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Sostituisci quanto segue:

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

L'output è simile al seguente esempio:

- name: projects/1234567890/locations/us-central1/agents/my-travel-agent
  displayName: Travel Orchestrator Agent
  description: 'Decomposes natural language travel requests into sub-tasks.'
  version: 1.0.0
  protocols:
    - type: A2A_AGENT
      protocolVersion: "0.3"
      interfaces:
        - url: https://api.example.com/.well-known/agent-card.json
          protocolBinding: HTTP_JSON
  attributes:
    agentregistry.googleapis.com/system/Framework:
      framework: "google-adk"
    agentregistry.googleapis.com/system/RuntimeIdentity:
      identity: "principal://..."
  card:
    type: A2A_AGENT_CARD
    content: {...}

Il campo card contiene tutti i contenuti della scheda dell'agente A2A, se disponibili.

Filtra gli agenti registrati

Se hai più agenti o se vuoi confermare la registrazione di un agente specifico, puoi filtrare l'elenco in base ai metadati dell'agente:

Console

1. Nella console Google Cloud , vai a Registro agenti:

   Vai al registry degli agenti

2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

3. Seleziona la scheda Agenti.

   La pagina mostra un elenco di tutti gli agenti registrati e i relativi dettagli, ad esempio nome, identificatore, descrizione, runtime e posizione.

4. Filtra l'elenco in base alla posizione dell'agente o alla sua risorsa di runtime:

   • Per filtrare in base alla località, fai clic sul menu Località, seleziona le località che vuoi filtrare e fai clic su Applica.
   • Per filtrare in base alla durata, fai clic sul menu Durata, seleziona le durate che vuoi filtrare e fai clic su Applica.

   La pagina mostra un elenco filtrato degli agenti registrati per le condizioni selezionate.

gcloud

Filtra l'elenco degli agenti in modo da restituire solo le risorse che corrispondono a coppie chiave/valore specifiche utilizzando il flag --filter:

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto.
• REGION: la regione del registro.
• FILTER_EXPRESSION: l'espressione di filtro per gli agenti che vuoi filtrare. Ad esempio, per filtrare per nome visualizzato, puoi utilizzare displayName='DISPLAY_NAME'. Per filtrare in base all'identificatore (URN) univoco a livello globale, puoi utilizzare agentId='urn:agent:AGENT_URN'.

Visualizzare i dettagli dell'agente

Se hai identificato un agente che vuoi utilizzare, puoi recuperare i relativi metadati completi, inclusi l'endpoint di runtime e l'elenco completo delle competenze:

Console

1. Nella console Google Cloud , vai a Registro agenti:

   Vai al registry degli agenti

2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

3. Seleziona la scheda Agenti.

   La pagina mostra un elenco di tutti gli agenti registrati e i relativi dettagli, ad esempio nome, identificatore, descrizione, runtime e posizione.

4. Fai clic sul nome dell'agente che vuoi visualizzare.

   La pagina dei dettagli include schede per i dettagli dell'agente.

5. Fai clic sulla scheda corrispondente per visualizzare i dettagli specifici dell'agente.

   La disponibilità delle funzionalità dipende dal runtime. Schede come Sessioni, Playground, Memorie e Valutazione sono funzionalità specifiche che vengono visualizzate per gli agenti creati su runtime gestiti, come Vertex AI Agent Engine:

   • Panoramica: dettagli principali dell'agente, tra cui nome, identificatore, posizione, descrizione e runtime. La panoramica mostra anche le competenze e l'URI risorsa, necessari per creare query nel grafico della topologia.
   • Osservabilità: approfondimenti incentrati sulle applicazioni, come latenza, traffico, errori e spesa dei token. Questa scheda si integra con gli strumenti di Google Cloud Observability per visualizzare le metriche delle prestazioni in tempo reale e l'utilizzo a livello di sistema per aiutarti a gestire i costi e l'esperienza utente. Per saperne di più, consulta la Panoramica dell'osservabilità.
   • Tracce: il percorso esatto di una conversazione passo dopo passo, inclusa la formattazione dettagliata dei messaggi di input e dell'assistente per eseguire il debug di complessi cicli di ragionamento multi-agente o errori di chiamata di strumenti in tempo reale. Per saperne di più, consulta Visualizzare le tracce dell'agente.
   • Sicurezza: risultati di Model Armor e Security Command Center, incluse violazioni delle norme relative ai contenuti, rischi di perdita di dati e valutazioni di conformità. Per ulteriori informazioni sulla sicurezza, vedi Visualizzare i risultati di sicurezza.
   • Topologia: una mappa visiva delle relazioni e dei flussi di traffico tra un agente, il gateway agente assegnato e i server MCP con cui interagisce. Per saperne di più su Agent Gateway, consulta la panoramica di Agent Gateway. Per ulteriori informazioni sulla topologia, vedi Visualizzare i grafici per un agente registrato.
   • Identità: l'entità agente utilizzata per l'applicazione delle norme. Utilizzi questa identità, ad esempio, per configurare i binding del provider di autenticazione per l'autenticazione a strumenti e risorse.
   • Sessioni: cronologia delle conversazioni persistente e monitoraggio delle interazioni attive con l'agente.
   • Playground: un'interfaccia di chat diretta per testare il comportamento dell'agente.
   • Memorie: funzionalità di personalizzazione a lungo termine che generano o richiamano dettagli delle conversazioni passate con l'agente per preservare il contesto nelle interazioni.
   • Valutazione: dettagli di tutte le attività di valutazione dell'agente. Questa scheda ti consente di creare nuove attività di valutazione, caricare metriche e valutare le prestazioni cognitive dell'agente e l'affidabilità del modello rispetto al traffico live o a simulazioni sintetiche.

gcloud

Per visualizzare i metadati dettagliati di un agente specifico, utilizza il comando agents describe:

gcloud alpha agent-registry agents describe AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Sostituisci quanto segue:

• AGENT_NAME: il nome dell'agente, ad esempio my-travel-agent.
• PROJECT_ID: l'ID progetto.
• REGION: la regione del registro.

Con l'endpoint dell'agente, le definizioni delle skill e i metadati di sola output, come il framework sottostante, l'identità di runtime e il payload completo della scheda dell'agente A2A, puoi associare in modo sicuro l'agente ai workflow dell'orchestratore utilizzando l'Agent Development Kit (ADK) o le richieste API standard.

Passaggi successivi

• Scopri come visualizzare le relazioni tra agenti utilizzando un grafico della topologia.
• Scopri come gestire gli agenti, incluso l'aggiornamento dei metadati.
• Scopri come cercare agenti e strumenti utilizzando query in linguaggio naturale.