Utilizzare l'analisi degli agenti BigQuery

BigQuery agent analytics è una soluzione open source che ti consente di acquisire, analizzare e visualizzare su larga scala i dati di interazione degli agenti multimodali trasmettendo in streaming le interazioni degli agenti non elaborate, come richieste, risposte, chiamate di strumenti ed errori, direttamente in BigQuery. Questa soluzione ti consente di eseguire valutazioni basate sull'AI, ottimizzare i prompt degli agenti ed estrarre la memoria a lungo termine per migliorare le interazioni future. L'analisi degli agenti BigQuery è supportata in Agent Development Kit (ADK) e LangGraph (anteprima).

Architettura

BigQuery agent analytics trasmette i dati sull'attività dell'agente a BigQuery utilizzando l'API BigQuery Storage Write, che fornisce lo streaming di log a basso throughput e bassa latenza senza bloccare l'esecuzione dell'agente.

Il flusso di dati è composto dalle seguenti fasi:

  1. Acquisisci. Utilizza i plug-in in Agent Development Kit (ADK) o i callback in LangGraph intercetta gli eventi di interazione per acquisire gli eventi dell'agente.
  2. Stream. Gli eventi di interazione vengono inviati a BigQuery tramite l'API Storage Write. Se non esiste uno schema standardizzato, l'agente ne crea uno automaticamente.
  3. Consume. Analizza e valuta i dati degli agenti registrati. Puoi eseguire query sui dati non elaborati con SQL, monitorare le metriche su dashboard personalizzate o utilizzare l' SDK BigQuery Agent Analytics per ricostruire e valutare tracce di esecuzione complesse di agent multi-turn.

Diagramma che mostra i dati sull'attività degli agenti che fluiscono dai framework di orchestrazione in BigQuery per l'analisi.

Vantaggi dell'analisi degli agenti

  • Abilita la registrazione completa con una sola riga di codice e automatizza la gestione dello schema.
  • Registra e analizza dati multimodali, come testo, immagini, video e audio, utilizzando le tabelle degli oggetti.
  • Monitora le metriche operative, come il consumo di token e la latenza, all'interno di uno schema robusto e predefinito.
  • Identifica le opportunità di ottimizzazione utilizzando le funzioni di AI generativa e la ricerca vettoriale di BigQuery.
  • Proteggi i log degli agenti con controlli di accesso granulari, mascheramento dei dati e crittografia.

Metodi per acquisire i dati dei log dell'agente

Per acquisire la telemetria delle interazioni dell'agente (richieste, risposte, chiamate di strumenti e log degli errori) in modo nativo in BigQuery, puoi registrare i dati degli eventi in diversi modi:

  • Plug-in del framework di orchestrazione: utilizza i plug-in di logging standard forniti dal toolkit di orchestrazione degli agenti. Ad esempio, l'BigQueryAgentAnalyticsPlugin in Agent Development Kit (ADK) si collega all'agente runner per intercettare, serializzare e trasmettere automaticamente gli eventi.
  • Gestori di callback del framework: integra i callback standard in ambienti di agenti popolari. Ad esempio, puoi utilizzare il gestore BigQuery integrato in LangGraph e LangChain per intercettare e inoltrare le tracce.
  • Importazione diretta dell'API: per framework personalizzati o proprietari, utilizza le librerie clientGoogle Cloud per trasmettere in streaming gli eventi strutturati direttamente alla tabella degli eventi utilizzando l'API Storage Write.

Indipendentemente dal metodo, tutte le opzioni di logging utilizzano l'API BigQuery Storage Write a bassa latenza e ad alta velocità effettiva. Questa API fornisce un endpoint di streaming solido che memorizza nel buffer e serializza le righe (utilizzando il motore PyArrow) in modo asincrono in memoria prima di eseguirne il commit, garantendo che le attività della pipeline di osservabilità non blocchino i turni di esecuzione dell'agente rivolto agli utenti.

Modi per analizzare i dati dei log dell'agente

Per comprendere e ottimizzare il rendimento del tuo agente, analizza e valuta i log delle interazioni nei seguenti modi:

  • Query SQL dirette: esegui query personalizzate in BigQuery per calcolare metriche come il consumo di token e la latenza di esecuzione. Puoi anche utilizzare AI.GENERATE per l'analisi automatica della causa principale degli errori o eseguire unioni con tabelle aziendali per misurare l'impatto sull'attività.
  • Dashboard interattive: collega strumenti di visualizzazione come Data Studio a viste BigQuery predefinite o personalizzate per monitorare lo stato degli agenti, i tassi di errore e le tendenze di utilizzo nel tempo.
  • Notebook Jupyter: esplora e sperimenta con i dati di log utilizzando librerie Python, pandas o BigFrames in ambienti interattivi.
  • SDK Python: esegui query, ricostruisci e controlla a livello di programmazione le tracce di esecuzione degli agenti direttamente nel codice dell'applicazione o nelle pipeline di valutazione automatizzate.

Esempi di utilizzo dei dati dei log degli agenti

Di seguito sono riportati casi d'uso ed esempi comuni di utilizzo dei dati di log dell'agente in BigQuery.

Metriche operative e di osservabilità

  • Esegui query sui dati per suddividere i costi in base ai flussi degli agenti e determinare se un agente specifico, ad esempio un agente di perfezionamento, consuma una quantità sproporzionata di token rispetto al suo contributo alle risposte finali.
  • Utilizza l'agente di analisi conversazionale BigQuery per l'analisi della causa principale basata sull'AI eseguendo query con la funzione AI.GENERATE. Ad esempio, "Analizza questo log della conversazione e spiega la causa principale dell'errore".

Valutazione dell'agente e analisi della qualità

  • Classifica le conversazioni e misura la classificazione degli agenti nel tempo utilizzando la funzione AI.SCORE.
  • Identifica i cluster di conversazioni in cui l'agente non è riuscito ad assistere gli utenti utilizzando una query SQL con Vector Search e poi confrontali con l'intent originale dell'utente. In questo modo puoi identificare le lacune negli strumenti o nella knowledge base dell'agente.

Approfondimenti e contestualizzazione aziendali

Per contestualizzare i dati dell'agente, unisci la tabella agent_events ad altre tabelle aziendali . Ad esempio, mostra il valore medio dell'ordine (AOV) per i clienti che hanno interagito con l'agente AI rispetto a quelli che hanno utilizzato la barra di ricerca.

Per altri esempi, vedi Query di analisi avanzata.

Utilizzare un notebook Jupyter per lavorare con i log degli agenti

Utilizza questo notebook Jupyter di Colab di esempio per eseguire query, visualizzare e valutare in modo interattivo i log degli agenti.

Utilizzare l'SDK BigQuery Agent Analytics

L'SDK BigQuery agent analytics è una libreria Python open source che fornisce un livello di consumo e valutazione per l'osservabilità a lungo termine degli agenti. Le dashboard e i blocchi note sono eccellenti per l'esplorazione ad hoc e l'SDK fornisce un modo per analizzare e controllare sistematicamente il comportamento degli agenti su larga scala.

Cosa puoi fare con l'SDK

Puoi eseguire le seguenti attività utilizzando l'SDK BigQuery Agent Analytics. Per esempi dettagliati di analisi dei log, consulta il repository GitHub per l'SDK.

  • Ricostruzione della traccia: ricostruisci i log degli eventi polimorfici in catene causali di eventi per eseguire il debug delle sessioni in più turni, incluse chiamate nidificate di strumenti e LLM.
  • Valutazione deterministica e semantica: valuta la qualità dell'agente in base a criteri basati su regole, come latenza, numero di turni e tassi di errore, nonché a criteri semantici, come correttezza, sentiment e allucinazioni.
  • Corrispondenza delle traiettorie: confronta i percorsi di esecuzione effettivi dell'agente con le traiettorie di riferimento previste per verificare l'efficienza dei passaggi e se gli strumenti sono stati utilizzati nell'ordine corretto.
  • Monitoraggio comportamentale e rilevamento della deriva: esegui analisi statistiche sui risultati non deterministici dell'agente, monitora le distribuzioni delle richieste degli utenti e rileva la regressione della produzione o la deriva semantica.
  • Memoria dell'agente a lungo termine: fornisce agli agenti un contesto cross-sessione, il recupero semantico del profilo utente e una memoria episodica consapevole del budget di token memorizzata in modo nativo in BigQuery.

Registrare e analizzare l'attività degli agenti

L'integrazione dell'SDK nei workflow degli agenti in genere prevede i seguenti passaggi:

  1. Registra interazioni: collega un plug-in logger (ad esempio BigQueryAgentAnalyticsPlugin in ADK) o un gestore callback nel framework di orchestrazione dell'agente. Quando gli utenti interagiscono con il tuo agente, i log vengono trasmessi in streaming in modo asincrono a BigQuery utilizzando l'API Storage Write ad alta velocità effettiva.

  2. Inizializza il client: connettiti al tuo set di dati dei log dall'SDK Python:

    from google.cloud import bigquery
from bigquery_agent_analytics import Client

client = Client(
    project_id="YOUR_PROJECT_ID",
    dataset_id="YOUR_DATASET_ID",
    table_id="agent_events",
)

    Lo snippet utilizza i seguenti componenti:

    • client: l'istanza Client principale che instrada programmaticamente le query e gestisce le connessioni di database attive.
    • project_id: l'ID progetto Google Cloud che ospita il set di dati di destinazione.
    • dataset_id: il nome del set di dati BigQuery in cui vengono archiviati i log.
    • table_id: la tabella specifica che archivia gli eventi di telemetria (agent_events per impostazione predefinita).

  3. Ricostruire una traccia della sessione: recupera una sessione di conversazione specifica per visualizzare ed esaminare la sequenza esatta di eventi:

    trace = client.get_trace(
    session_id="YOUR_SESSION_ID"
)
trace.render()

    Lo snippet utilizza i seguenti componenti:

    • trace: l'oggetto Trace idratato che contiene l'albero di intervalli DAG gerarchico collegato causalmente di tutte le azioni dell'utente e dell'agente.
    • YOUR_SESSION_ID: l'ID univoco della sessione che vuoi esaminare.

  4. Esegui valutazioni automatiche: calcola in modo programmatico le traiettorie delle sessioni o verifica la regressione rispetto a una suite di test di riferimento:

    from bigquery_agent_analytics.evaluators import CodeEvaluator, LLMAsJudge
from bigquery_agent_analytics.grader_pipeline import GraderPipeline

# Create a grader pipeline with deterministic and semantic metrics
evaluator = GraderPipeline(
    graders=[
        CodeEvaluator.latency(threshold_ms=5000),
        LLMAsJudge.correctness(),
    ]
)
report = client.evaluate(evaluator, session_ids=["session_1", "session_2"])
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    Lo snippet utilizza i seguenti componenti:

    • evaluator: la logica strutturata GraderPipeline che compone metriche di valutazione semantica e basate su regole eterogenee.
    • session_ids: l'elenco delle stringhe ID sessione su cui eseguire valutazioni batch in BigQuery.
    • report: l'oggetto EvaluationReport risultante contenente i voti grezzi della sessione, i riepiloghi delle metriche, le statistiche della prova e il feedback del valutatore automatico.

Integra l'analisi degli agenti BigQuery nel tuo flusso di lavoro

Per integrare l'analisi degli agenti BigQuery nel tuo flusso di lavoro, consulta la documentazione del tuo framework:

Passaggi successivi