Gestisci agenti

La gestione efficace del parco risorse di agenti richiede di mantenere la precisione del registro visualizzando e aggiornando i dettagli del servizio man mano che i carichi di lavoro si evolvono, sostituendo i metadati o rimuovendo gli agenti non più in uso.

Questo documento descrive in dettaglio come visualizzare e modificare i dettagli e la configurazione dell'agente registrato.

Prima di iniziare

Prima di gestire gli agenti, assicurati che i tuoi agenti siano registrati 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 gestire gli agenti registrati in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Editor API Agent Registry (roles/agentregistry.editor) sul 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.

Scopri gli agenti disponibili

Dopo aver registrato gli agenti, puoi scoprirli nel tuo ambiente e visualizzarne le configurazioni dettagliate, come endpoint, competenze e metadati associati.

Elenca e visualizza gli agenti

Puoi elencare tutti gli agenti registrati nel tuo ambiente e visualizzarne le configurazioni dettagliate , come endpoint, competenze e metadati associati:

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. L'elenco include il nome, l'identificatore, tipo, la descrizione, la versione, il runtime e la località dell'agente.

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

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.

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 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. L'elenco include il nome, l'identificatore, tipo, la descrizione, la versione, il runtime e la località dell'agente.

  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 metadati specifici utilizzando il flag --filter:

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

Sostituisci FILTER_EXPRESSION con l'espressione di filtro per gli agenti che vuoi filtrare. Ad esempio, puoi utilizzare i seguenti filtri:

  • Per filtrare in base al nome visualizzato, utilizza displayName='DISPLAY_NAME'.
  • Per cercare in base all'identificatore univoco globale (URN), utilizza agentId='urn:agent:AGENT_URN'.

Visualizza i dettagli di un agente

Visualizza i dettagli di un agente specifico, inclusi protocolli, competenze e identità:

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. L'elenco include il nome, l'identificatore, tipo, la descrizione, la versione, il runtime e la località dell'agente.

  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 gateway dell'agente assegnato e i server MCP con cui interagisce. Per saperne di più su Agent Gateway, consulta la panoramica su 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 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 il rendimento cognitivo 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 AGENT_NAME con il nome dell'agente, ad esempio my-custom-agent.

Aggiorna i metadati e gli endpoint dell'agente

Se l'URL del runtime dell'agente cambia o se vuoi sostituire il nome visualizzato, la descrizione o la specifica, puoi aggiornare i metadati dell'agente.

Per l'API Agent Registry, le risorse Agent vengono utilizzate per la rilevabilità. Pertanto, devi aggiornare direttamente la risorsa Service registrata.

Utilizza Google Cloud CLI con flag specifici per modificare i parametri dell'agente:

  • Aggiorna il nome visualizzato e la descrizione: utilizza i flag --display-name e --description, ad esempio:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="New display name" \
  --description="Updated description of the agent's purpose."

    Sostituisci quanto segue:

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

  • Aggiorna l'URL dell'endpoint: utilizza il flag --interfaces per specificare il nuovo endpoint, ad esempio:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

    Sostituisci quanto segue:

    • ENDPOINT_URL: il nuovo URL dell'endpoint del servizio agente, ad esempio https://new-api.example.com/agent.
    • PROTOCOL: il binding del protocollo per l'endpoint. I valori validi sono HTTP_JSON, GRPC o JSONRPC.

  • Aggiorna la specifica dell'agente: utilizza il flag --agent-spec-content, ad esempio se hai una nuova scheda dell'agente:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --agent-spec-content=@AGENT_SPEC

    Sostituisci AGENT_SPEC con il nome della nuova specifica dell'agente, ad esempio new-agent-card.json.

Rimuovi un agente

Per eliminare gli agenti registrati automaticamente in Agent Registry, devi eliminare l'agente sottostante nel suo specifico Google Cloud runtime. L'agente viene quindi rimosso automaticamente dal registro.

Per rimuovere un agente registrato manualmente dal registro, devi eliminare la risorsa Service sottostante. Questa azione rimuove l'agente dai risultati di ricerca e lo rende non rilevabile per altri strumenti:

gcloud alpha agent-registry services delete AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Sostituisci quanto segue:

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

Passaggi successivi