Gestisci agenti

Agent Registry ti consente di ispezionare, aggiornare e rimuovere gli agenti registrati in modo che il registro rifletta accuratamente le funzionalità attive nel tuo ecosistema di AI. Puoi elencare e visualizzare tutti gli agenti registrati, aggiornare i metadati o l'endpoint degli agenti registrati manualmente e rimuovere gli agenti che non sono più in uso.

Prima di iniziare

  1. Configura Agent Registry.

  2. Recupera l'ID progetto per il progetto di governance in cui è abilitato Agent Registry.

  3. Registra i tuoi agenti in Agent Registry.

  4. Per utilizzare i comandi di Google Cloud CLI in questo documento, configura 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 di governance in cui è abilitato Agent Registry. 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 visualizzare le loro configurazioni dettagliate, come gli endpoint, le skill A2A e i metadati associati.

Elencare e visualizzare tutti gli agenti

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

Console

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

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il progetto Google Cloud 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 località dell'agente.

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

gcloud

Per elencare tutti gli agenti in una località specifica, esegui il comando gcloud agent-registry agents list:

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

Sostituisci quanto segue:

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

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 Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il progetto Google Cloud 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 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à da 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 che restituisca solo le risorse corrispondenti a metadati specifici passando il flag --filter al comando gcloud agent-registry agents list:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • REGION: la regione del registry.
  • FILTER_EXPRESSION: 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 eseguire la ricerca in base all'identificatore dell'agente (URN) univoco a livello globale, utilizza agentId='urn:agent:AGENT_URN'.

Terraform

Per recuperare un agente registrato specifico filtrando in base ai suoi metadati, configura l'origine dati google_agent_registry_agent con l'argomento filter:

data "google_agent_registry_agent" "filtered_agent" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

Sostituisci quanto segue:

  • REGION: la regione del registry.
  • DISPLAY_NAME: il nome leggibile dell'agente in base al quale filtrare, ad esempio Support Agent.

Visualizza i dettagli di un agente

Visualizza i dettagli di un agente specifico, inclusi i suoi protocolli, le sue competenze A2A e la sua identità:

Console

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

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il progetto Google Cloud 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 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 dell'agente specifico.

    La disponibilità delle funzionalità dipende dal runtime. Schede come Sessioni, Playground, Memorie e Valutazione sono funzionalità specifiche che vengono visualizzate per gli agenti basati su runtime gestiti, come Agent Runtime su Gemini Enterprise Agent Platform:

    • Panoramica: dettagli principali dell'agente, tra cui il nome, l'identificatore, la località, la descrizione e il runtime dell'agente. La panoramica mostra anche le competenze A2A e il riferimento di runtime, 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 sul 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 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 cicli di ragionamento multi-agente complessi o errori di chiamata degli strumenti in tempo reale. Per saperne di più, consulta Visualizza le tracce dell'agente.
    • Sicurezza: risultati di Model Armor e Security Command Center, tra cui violazioni delle norme relative ai contenuti, rischi di fuga di dati e valutazioni della conformità. Per saperne di più sulla sicurezza, consulta Visualizza i risultati relativi alla sicurezza.
    • Topologia: una mappa visiva delle relazioni e dei flussi di traffico tra un agente, l'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 Visualizza i grafici per un agente registrato.
    • Identità: l'entità dell'agente utilizzata per l'applicazione delle policy. Utilizza questa identità, ad esempio, per configurare le associazioni dei 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.
    • Ricordi: funzionalità di personalizzazione a lungo termine che generano o richiamano dettagli delle conversazioni passate con l'agente per preservare il contesto tra le interazioni.
    • Valutazione: dettagli di tutte le attività di valutazione degli agenti. 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 in tempo reale o alle simulazioni sintetiche.

gcloud

Per visualizzare i metadati dettagliati di un agente specifico, esegui il comando gcloud agent-registry agents describe:

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

Sostituisci quanto segue:

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

Terraform

Per recuperare i dettagli di un agente registrato specifico utilizzando il suo ID, configura l'origine dati google_agent_registry_agent:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  agent_id = "AGENT_ID"
}

output "agent_create_time" {
  description = "The timestamp when the agent was registered."
  value       = data.google_agent_registry_agent.my_agent.create_time
}

output "agent_update_time" {
  description = "The timestamp when the agent was last updated."
  value       = data.google_agent_registry_agent.my_agent.update_time
}

Sostituisci quanto segue:

  • REGION: la regione del registry.
  • AGENT_ID: l'identificatore univoco del tuo agente, ad esempio my-custom-agent.

Aggiorna i metadati e gli endpoint dell'agente

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

In Agent Registry, le risorse Agent sono risorse di rilevamento di sola lettura. Per aggiornare un agente registrato manualmente, devi aggiornare direttamente la sua risorsa Service scrivibile. Per gli agenti registrati automaticamente, aggiorna l'agente nel runtime sottostante in modo che Agent Registry sincronizzi le modifiche.

Console

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

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

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il progetto Google Cloud 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 località 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 dell'agente, ad esempio il nuovo nome o la nuova descrizione.

  7. Fai clic su Salva.

gcloud

Esegui il comando gcloud agent-registry services update 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 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 registry.

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

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

    Sostituisci quanto segue:

    • AGENT_NAME: il nome dell'agente, ad esempio my-support-agent.
    • PROJECT_ID: l'ID progetto
    • REGION: la regione del registry.
    • ENDPOINT_URL: il nuovo URL dell'Agent Endpoint, 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 agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --agent-spec-content=AGENT_SPEC_FILE

    Sostituisci quanto segue:

    • AGENT_NAME: il nome dell'agente, ad esempio my-support-agent.
    • PROJECT_ID: l'ID progetto
    • REGION: la regione del registry.
    • AGENT_SPEC_FILE: il percorso del nuovo file di specifica dell'agente, ad esempio new-agent-card.json. La dimensione massima del file di specifica è 10 kB.

Terraform

Per aggiornare i metadati, l'URL dell'endpoint o la specifica dell'agente registrato, modifica i parametri della risorsa google_agent_registry_service esistente nella configurazione, quindi esegui terraform apply:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "New Display Name"
  description  = "Updated description of the agent's purpose."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

Sostituisci quanto segue:

  • REGION: la regione del registry.
  • AGENT_NAME: il nome univoco che vuoi assegnare al tuo agente, ad esempio my-support-agent.
  • ENDPOINT_URL: l'URL dell'endpoint API dell'agente, ad esempio https://api.example.com/v1/agents/1234.
  • PROTOCOL: l'associazione del protocollo per l'endpoint. I valori validi sono HTTP_JSON, GRPC o JSONRPC.

Rimuovi un agente

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

Per rimuovere un agente registrato manualmente dal registry, devi eliminare la relativa risorsa Service. 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 Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il progetto Google Cloud 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 località 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, inserisci DELETE per confermare l'azione.

  7. Fai clic su Elimina.

gcloud

Esegui il comando gcloud agent-registry services delete:

gcloud 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 registry.

Terraform

Rimuovi la risorsa google_agent_registry_service che rappresenta l'agente dalla configurazione Terraform, quindi esegui terraform apply.

Passaggi successivi