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 tracciabilità per diversi tipi di agenti, vedi Configurare la tracciabilità.
  • 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 > Registro degli agenti.

    Vai a Agent Registry

  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 span, 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 richiesta end-to-end, che rappresentano un singolo percorso di esecuzione.
  • Visualizzazione intervallo:fornisce un elenco granulare di singole operazioni (intervalli) eseguite all'interno delle tracce, ad esempio una chiamata specifica del 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 in quella 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à, Gemini Enterprise Agent Platform separa i metadati operativi dai contenuti conversazionali effettivi:

  • Attributi e metriche 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 Storage (opzione consigliata) o Cloud Logging, a seconda della configurazione dell'organizzazione. Cloud Storage è consigliato perché supporta payload di grandi dimensioni e multimodali senza troncamento e fornisce una gestione del ciclo di vita granulare. Cloud Logging supporta payload di testo di base, ma ha limiti di dimensioni. Questa separazione consente agli amministratori di implementare controlli granulari di Identity and Access Management (IAM) sui dati conversazionali sensibili.

L'interfaccia utente di Gemini Enterprise Agent Platform 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