Visualizzare le tracce dell'agente

Prima di iniziare

Prima di poter visualizzare le tracce dell'agente, devi soddisfare i seguenti requisiti:

  • Abilita le API: assicurati che le seguenti API siano abilitate per il tuo progettoGoogle Cloud :
    • API Cloud Trace
    • API Cloud Logging
    • API Telemetry
  • Configura la tracciabilità dell'agente: l'agente deve essere configurato per inviare dati di tracciamento a Google Cloud. Per istruzioni sull'attivazione della traccia per diversi tipi di agenti, vedi Configurare la traccia.
  • Configura le autorizzazioni: per visualizzare le tracce e i log, devi disporre di ruoli IAM che forniscano le autorizzazioni richieste, ad esempio i ruoli Utente Cloud Trace (roles/cloudtrace.user) e Visualizzatore log (roles/logging.viewer). Per saperne di più, consulta Controllo dell'accesso di Cloud Trace e Controllo dell'accesso di Cloud Logging.

Il tracciamento distribuito è una tecnica diagnostica che monitora l'avanzamento di una singola richiesta mentre attraversa vari servizi e componenti distribuiti nell'architettura. Poiché gli agenti di AI generativa utilizzano cicli di ragionamento non deterministici per scegliere dinamicamente strumenti e percorsi di esecuzione, le metriche convenzionali point-in-time spesso non sono sufficienti per il debug. Le tracce sono essenziali per l'osservabilità degli agenti perché forniscono una sequenza temporale completa e sequenziale di queste interazioni imprevedibili, consentendoti di vedere esattamente perché un agente ha preso una decisione specifica.

Esplorare le tracce

Per accedere ai dati di esecuzione dettagliati per un agente:

  1. Nella console Google Cloud , vai alla pagina Agent Platform > Agent Registry.

    Vai al registry degli agenti

  2. Seleziona l'agente specifico.

  3. Fai clic sulla scheda Tracce.

Questa interfaccia ti consente di esaminare i dettagli di esecuzione passo passo del tuo agente. Una traccia è un record fattuale e immutabile del comportamento dell'agente, inclusi input, risposte e chiamate agli strumenti del modello. La visualizzazione della traccia include un grafo diretto aciclico (DAG) dei relativi intervalli, input e output e attributi dei metadati.

La scheda Tracce fornisce tre visualizzazioni distinte per esplorare i dati di telemetria:

  • Visualizzazione sessione:raggruppa le esecuzioni in base alle singole sessioni utente, consentendoti di analizzare le conversazioni multi-turn e il comportamento dell'agente nel tempo.
  • Visualizzazione traccia:si concentra sulle singole tracce di richieste end-to-end, che rappresentano un singolo percorso di esecuzione.
  • Visualizzazione span:fornisce un elenco granulare di singole operazioni (span) eseguite all'interno delle tracce, ad esempio una chiamata specifica al modello di base, una richiesta API o l'esecuzione di uno strumento esterno.

Visualizzazione di una singola traccia (contesto sessione)

Quando selezioni una sessione specifica dalla visualizzazione Sessione, si apre un riquadro dei dettagli con un riquadro elenco sul lato sinistro che mostra tutte le singole tracce contenute nella sessione multi-turno. Il pannello principale aggrega l'intero contesto della sessione, visualizzando l'input formattato e i messaggi dell'assistente, insieme alle metriche generali della sessione, come durata, token GenAI totali e punteggi di valutazione continua.

Visualizzazione di una singola traccia (traccia diretta o contesto dello span)

In alternativa, se selezioni una traccia specifica dalla visualizzazione Traccia o uno span distinto dalla visualizzazione Span, il riquadro dei dettagli si apre direttamente su quella esecuzione specifica. Poiché stai visualizzando una singola operazione anziché una sessione raggruppata, il riquadro dell'elenco a sinistra è nascosto, consentendo un'ispezione immediata e mirata della latenza, degli attributi e dei potenziali errori specifici di quell'operazione.

Archiviazione dei dati e controllo dell'accesso

Per mantenere la sicurezza e la conformità, la piattaforma Gemini Enterprise Agent separa i metadati operativi dal contenuto conversazionale effettivo:

  • Metriche e attributi di esecuzione:la telemetria standard (come latenza, codici di stato e metadati strutturali) viene archiviata direttamente negli intervalli di traccia.
  • Prompt e risposte:i dati potenzialmente sensibili, come i prompt degli utenti e le risposte del modello, non vengono memorizzati negli span. Vengono invece indirizzati a Cloud Logging o Cloud Storage, a seconda della configurazione della tua organizzazione. In questo modo, gli amministratori possono implementare controlli IAM (Identity and Access Management) granulari sui dati conversazionali sensibili.

La UI della piattaforma agentica Gemini Enterprise comprende automaticamente la correlazione sottostante tra gli intervalli di traccia e questi log di prompt e risposte archiviati in modo sicuro. Quando apri una visualizzazione dei dettagli della traccia, la piattaforma ricompone senza problemi questi dati presentando una visualizzazione unificata del comportamento dell'agente senza compromettere le regole di governance dei dati.

Per ulteriori informazioni sulla configurazione delle destinazioni di archiviazione per i dati conversazionali, consulta Raccogliere e visualizzare prompt e risposte multimodali.

Passaggi successivi