Guida rapida: scopri un agente

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

Questa guida rapida mostra come rilevare 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 avere l'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 rilevare 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.

Elencare gli agenti disponibili

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

Console

  1. Nella Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  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, come nome, identificatore, descrizione, runtime e località.

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

gcloud

Per elencare tutti gli agenti in una località 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 l'intero contenuto della scheda dell'agente A2A, se disponibile.

Filtrare 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 Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  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, come nome, identificatore, descrizione, runtime e località.

  4. Filtra l'elenco in base alla località dell'agente o alla 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 al runtime, fai clic sul menu Runtime , seleziona i runtime 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 in base al nome visualizzato, puoi utilizzare displayName='DISPLAY_NAME'. Per filtrare in base all' identificatoreunivoco globale (URN), 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 Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  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, come nome, identificatore, descrizione, runtime e località.

  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, Sandbox, Ricordi 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, inclusi nome, identificatore, località, descrizione e runtime. La panoramica mostra anche le competenze e l' URI della risorsa, necessari per creare query nel grafico della topologia.
    • Osservabilità: insight incentrati sulle applicazioni, come latenza, traffico, errori e spesa per i token. Questa scheda si integra con gli strumenti di Google Cloud Observability per visualizzare le metriche di rendimento 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 sull'osservabilità.
    • Tracce: il percorso esatto di un passaggio di conversazione passo dopo passo, inclusa la formattazione dettagliata dei messaggi di input e dell'assistente per eseguire il debug in tempo reale di loop di ragionamento multi-agente complessi o errori di chiamata di strumenti. Per saperne di più, consulta Visualizzare le tracce degli agenti.
    • Sicurezza: risultati di Model Armor e Security Command Center, tra cui violazioni delle norme sui contenuti, rischi di perdita di dati e valutazioni di conformità. Per saperne di più sulla sicurezza, consulta Visualizzare i risultati di sicurezza.
    • Topologia: una mappa visiva delle relazioni e dei flussi di traffico tra un agente, il relativo Agent Gateway assegnato e i server MCP con cui interagisce. Per saperne di più su Agent Gateway, consulta la panoramica di Agent Gateway. Per saperne di più sulla topologia, consulta Visualizzare i grafici per un agente registrato.
    • Identità: l'entità agente utilizzata per l'applicazione delle policy. Utilizza 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.
    • Sandbox: un'interfaccia di chat diretta per testare il comportamento dell'agente.
    • Ricordi: funzionalità di personalizzazione a lungo termine che generano o richiamano i dettagli delle conversazioni passate con l'agente per mantenere 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 alle 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 competenze e i metadati di sola uscita, 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 flussi di lavoro dell'orchestratore utilizzando l' Agent Development Kit (ADK) o le richieste API standard.

Passaggi successivi