Gestisci agenti

La gestione efficace del tuo parco risorse di agenti richiede di mantenere il registro accurato visualizzando e aggiornando i dettagli degli agenti man mano che il tuo ecosistema AI si evolve, eseguendo l'override dei 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 siano registrati nel registry degli agenti. Per eseguire queste attività, devi anche avere l'ID progetto.

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire gli agenti registrati in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Agent Registry API Editor (roles/agentregistry.editor) 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.

Scopri gli agenti disponibili

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

Elencare e visualizzare gli agenti

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

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

  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.

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

  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 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 per nome visualizzato, utilizza displayName='DISPLAY_NAME'.
  • Per eseguire la ricerca in base all'identificatore (URN) univoco a livello globale, utilizza agentId='urn:agent:AGENT_URN'.

Visualizzare i dettagli di un agente

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

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. L'elenco include il nome, l'identificatore, il tipo, la descrizione, la versione, il runtime e la posizione 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, Playground, Memorie ed Evaluation sono funzionalità specifiche che vengono visualizzate per gli agenti creati su runtime gestiti, come Agent Runtime su Gemini Enterprise Agent Platform:

    • Panoramica: i 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à: insight incentrati sulle applicazioni, come latenza, traffico, errori e spesa dei token. Questa scheda si integra con gli strumenti 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 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 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 recuperano dettagli dalle 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 AGENT_NAME con il nome del tuo agente, ad esempio my-custom-agent.

Aggiorna metadati ed endpoint dell'agente

Se l'URL di runtime dell'agente cambia o vuoi eseguire l'override del nome visualizzato, della descrizione o della specifica, puoi aggiornare i metadati dell'agente.

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

Console

Aggiorna i dettagli dell'agente disponibili dalla console Google Cloud :

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

  4. Fai clic sul nome dell'agente da aggiornare.

  5. Nella scheda Panoramica dell'agente, fai clic su Modifica.

  6. Nel riquadro Modifica servizio, inserisci le informazioni aggiornate del tuo agente, ad esempio il nuovo nome o la nuova descrizione.

  7. Fai clic su Salva.

gcloud

Utilizza gcloud 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 del tuo 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 dell'agente, ad esempio https://new-api.example.com/agent.
    • PROTOCOL: l'associazione 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 del nuovo file di specifica dell'agente, ad esempio new-agent-card.json. La dimensione massima del file di specifica è 10 KB.

Rimuovere un agente

Per eliminare gli agenti registrati automaticamente in Agent Registry, devi eliminare l'agente sottostante nel relativo runtime Google Cloud specifico. 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 da altri strumenti:

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

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

  5. Nella scheda Panoramica dell'agente, fai clic su Elimina.

  6. Nella finestra di dialogo di conferma, digita ELIMINA per confermare l'azione.

  7. Fai clic su Elimina.

gcloud 

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