Osservabilità per gli sviluppatori di agenti AI

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

Instrumentare 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:

  • Comprendere 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 selezionati.
  • Risolvere i problemi e diagnosticare gli errori: le tracce ti aiutano a identificare le richieste API non riuscite, i loop di esecuzione infiniti e i colli di bottiglia di latenza nei flussi di lavoro degli agenti distribuiti.
  • Supportare la governance e convalidare il traffico: la telemetria ti consente di visualizzare i flussi di comunicazione, ad esempio in Topologia dell'applicazione, per verificare che gli agenti comunichino solo con agenti, server MCP ed endpoint esterni autorizzati.
  • 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 di risorse.

Come instrumentare le applicazioni di AI generativa

L'instrumentazione dell'applicazione comporta la generazione di dati di telemetria e l'invio a una destinazione in cui i dati possono essere archiviati, sottoposti a query e analizzati. Ad esempio, quando l'instrumentazione invia dati di telemetria al tuo Google Cloud progetto, puoi utilizzare Google Cloud Observability per visualizzare e analizzare questi 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 collegati ai dati di traccia. Vengono invece archiviati in un bucket Cloud Storage. Per saperne di più su questa configurazione, consulta Raccogliere e visualizzare prompt e risposte multimodali.

Best practice

Ti consigliamo di instrumentare l'applicazione con OpenTelemetry, un progetto open source che fornisce un framework unificato per l'instrumentazione delle applicazioni. Gli esempi di instrumentazione 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 le 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 scarta 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?.

Esempi di instrumentazione

Per iniziare a utilizzare l'instrumentazione degli agenti, consulta le seguenti applicazioni di esempio e guide:

  • Raccogliere e visualizzare 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 anche come eseguire le seguenti operazioni:

    • Archiviare prompt e risposte in un bucket Cloud Storage.
    • Visualizzare prompt e risposte con la pagina Esplora tracce.
    • Analizzare prompt e risposte con BigQuery.
    • Valutare prompt e risposte con il Vertex AI SDK per Python.

  • Instrumentare un agente LangGraph ReAct con OpenTelemetry descrive come utilizzare OpenTelemetry per instrumentare un'applicazione di AI generativa che utilizza il framework LangChain o LangGraph. Fornisce anche un link a un'applicazione di esempio che puoi scaricare ed eseguire. L'applicazione di esempio raccoglie prompt e risposte di testo.

  • Instrumentare le applicazioni ADK con OpenTelemetry descrive come abilitare l'instrumentazione integrata che raccoglie dati di telemetria dalle azioni chiave dell'agente. I dati di telemetria includono prompt di testo e risposte dell'agente. Fornisce anche un link a un'applicazione di esempio che puoi scaricare ed eseguire. L'applicazione di esempio raccoglie prompt e risposte di testo.

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