Osservabilità per gli sviluppatori di agenti AI

Se sviluppi agenti AI, puoi strumentare le tue applicazioni con OpenTelemetry per osservare come i tuoi agenti ragionano, chiamano gli strumenti e rispondono ai prompt. Questa guida spiega come acquisire la telemetria degli agenti utilizzando framework come LangGraph e l'Agent Development Kit (ADK) e come analizzare i prompt e le risposte multimodali in Cloud Trace.

Strumenta gli agenti per comprenderne il comportamento

Quando sviluppi o gestisci applicazioni di AI generativa, i dati di telemetria acquisiscono i passaggi di ragionamento, le chiamate agli strumenti e le interazioni esterne dei tuoi agenti autonomi. Questi dati sono utili per i seguenti motivi:

  • Comprendi il comportamento non deterministico: poiché il processo di ragionamento di un agente non è deterministico, la telemetria è l'unico modo affidabile per esaminare le decisioni prese da un agente e gli strumenti che seleziona.
  • Risolvi i problemi e diagnostica gli errori: le tracce ti aiutano a identificare richieste API non riuscite, loop di esecuzione infiniti e colli di bottiglia della latenza negli Agentic Workflows distribuiti.
  • Supporta la governance e convalida il traffico: la telemetria ti consente di visualizzare i flussi di comunicazione, ad esempio nella topologia dell'applicazione, per verificare che i tuoi agenti comunichino solo con agenti autorizzati, server MCP ed endpoint esterni.
  • Valutare la qualità e il costo dell'output: la raccolta di prompt, risposte e utilizzo dei token ti aiuta a valutare l'accuratezza del modello, rilevare le allucinazioni e ottimizzare il consumo delle risorse.

Come puoi strumentare le tue applicazioni di AI generativa

La strumentazione dell'applicazione prevede la generazione di dati di telemetria e l'invio a una destinazione in cui i dati possono essere archiviati, interrogati e analizzati. Ad esempio, quando la strumentazione invia la telemetria al tuo progetto Google Cloud , puoi utilizzare Google Cloud Observability per visualizzare e analizzare i dati.

Cloud Trace estrae automaticamente gli eventi dagli intervalli scritti dalle applicazioni di AI generativa quando questi intervalli sono conformi alle convenzioni semantiche per intervalli ed eventi. Per informazioni su queste convenzioni, consulta i seguenti documenti:

Cloud Trace può anche visualizzare prompt e risposte multimodali. In questo scenario, i prompt e le risposte non sono allegati ai dati di traccia. Vengono invece archiviati in un bucket Cloud Storage. Per scoprire di più su questa configurazione, consulta Raccogli e visualizza prompt e risposte multimodali.

Best practice

Ti consigliamo di instrumentare la tua applicazione con OpenTelemetry, un progetto open source che fornisce un framework unificato per la strumentazione delle applicazioni. Gli esempi di strumentazione elencati in questo documento utilizzano OpenTelemetry.

Ti consigliamo inoltre di archiviare i prompt e le risposte in un bucket Cloud Storage anziché in una voce di log:

  • Hai un controllo granulare sui contenuti del bucket Cloud Storage. Ad esempio, puoi eliminare singole conversazioni archiviate in un bucket. Tuttavia, non puoi eliminare singole voci di log.

  • I bucket Cloud Storage possono archiviare oggetti molto più grandi della dimensione massima di una voce di log, che è limitata a 256 KiB. Cloud Logging risponde con un errore INVALID_ARGUMENT e ignora i dati se i dati ricevuti superano la dimensione massima della voce di log. Se il comando viene completato senza errori, ma i singoli campi superano i limiti di dimensione, Cloud Logging tronca i dati.

Per informazioni su OpenTelemetry, consulta Che cos'è OpenTelemetry?

Campioni di strumentazione

Per iniziare a utilizzare la strumentazione degli agenti, consulta le seguenti applicazioni di esempio e guide:

  • Raccogli e visualizza prompt e risposte multimodali descrive come configurare un agente LangGraph ReAct o un agente AI generativa creato con ADK per raccogliere prompt e risposte multimodali. Descrive inoltre come:

    • Archivia prompt e risposte in un bucket Cloud Storage.
    • Visualizza i prompt e le risposte con la pagina Esplora tracce.
    • Analizza i prompt e le risposte con BigQuery.
    • Valuta i prompt e le risposte con l'SDK Vertex AI Python.

  • Instrumenta un agente LangGraph ReAct con OpenTelemetry descrive come utilizzare OpenTelemetry per instrumentare un'applicazione di AI generativa che utilizza il framework LangChain o LangGraph. Inoltre, rimanda a un'applicazione di esempio che puoi scaricare ed eseguire. L'applicazione di esempio raccoglie prompt testuali e risposte.

  • Strumenta le applicazioni ADK con OpenTelemetry descrive come attivare la strumentazione integrata che raccoglie i dati di telemetria dalle azioni chiave dell'agente. La telemetria include prompt testuali e risposte dell'agente. Inoltre, rimanda a un'applicazione di esempio che puoi scaricare ed eseguire. L'applicazione di esempio raccoglie prompt testuali e risposte.

  • Esamina le chiamate MCP utilizzando Trace descrive come configurare l'applicazione per passare il contesto della traccia ai server MCP Google Cloud remoti, in modo che questi server possano collegare gli span a una traccia.