Utilizzare BigQuery Agent Analytics

BigQuery Agent Analytics è una soluzione open source che 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 consente di eseguire valutazioni basate sull'AI, ottimizzare i prompt degli agenti ed estrarre la memoria a lungo termine per migliorare le interazioni future. BigQuery Agent Analytics è supportato in Agent Development Kit (ADK) e LangGraph (anteprima).

Architettura

BigQuery Agent Analytics trasmette in streaming i dati delle attività degli agenti a BigQuery utilizzando l' API BigQuery Storage Write, che fornisce uno streaming di log a bassa latenza e ad alta velocità effettiva senza bloccare l'esecuzione degli agenti.

Il flusso di dati è composto dalle seguenti fasi:

  1. Acquisizione. Utilizza i plug-in in Agent Development Kit (ADK) o i callback in LangGraph per intercettare gli eventi di interazione e acquisire gli eventi degli agenti.
  2. Streaming. 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. Utilizzo. 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 degli agenti a più turni.

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

Vantaggi di Agent Analytics

  • Abilita la registrazione completa con una sola riga di codice e automatizza la gestione dello schema.
  • Registra e analizza i dati multimodali, come testo, immagini, video e audio, utilizzando le tabelle di 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 degli accessi granulari, mascheramento dei dati e crittografia.

Metodi per acquisire i dati dei log degli agenti

Per acquisire la telemetria di interazione 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, BigQueryAgentAnalyticsPlugin in Agent Development Kit (ADK) si collega all'esecutore dell'agente per intercettare, serializzare e trasmettere automaticamente gli eventi in streaming.
  • Gestori di callback del framework: integra i callback standard negli ambienti degli agenti più diffusi. Ad esempio, puoi utilizzare il gestore BigQuery integrato in LangGraph e LangChain per intercettare e inoltrare le tracce.
  • Importazione diretta dell'API: per i framework personalizzati o proprietari, utilizza le Google Cloud librerie client 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, alta velocità effettiva BigQuery Storage Write. Questa API fornisce un endpoint di streaming robusto che memorizza nel buffer e serializza le righe (utilizzando il motore PyArrow) in modo asincrono in memoria prima di eseguirne il commit, assicurando che le attività della pipeline di osservabilità non blocchino i turni di esecuzione degli agenti rivolti agli utenti.

Metodi per analizzare i dati dei log degli agenti

Per comprendere e ottimizzare il rendimento dell'agente, analizza e valuta i log di interazione 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 delle cause principali degli errori o eseguire join con le tabelle aziendali per misurare l'impatto sull'attività.
  • Dashboard interattive: collega gli strumenti di visualizzazione come Data Studio a visualizzazioni BigQuery predefinite o personalizzate per monitorare lo stato dell'agente, i tassi di errore e le tendenze di utilizzo nel tempo. I clienti di Looker possono anche utilizzare un modello di dashboard BigQuery Agent Analytics predefinito (Looker Block) dal Looker Marketplace.
  • Notebook Jupyter: esplora e sperimenta con i dati dei log utilizzando le 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 i casi d'uso comuni e gli esempi di utilizzo dei dati dei log degli agenti 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 di BigQuery per l'analisi delle cause principali basata sull'AI eseguendo query con la AI.GENERATE funzione. Ad esempio, "Analizza questo log di conversazione e spiega la causa principale dell'errore".

Valutazione degli agenti e analisi della qualità

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

Insight aziendali e contestualizzazione

Per contestualizzare i dati degli agenti, 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 ai clienti che hanno utilizzato la barra di ricerca.

Per altri esempi, consulta Query di analisi avanzate.

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à degli agenti a lungo termine. Le dashboard e i notebook 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 dell'SDK.

  • Ricostruzione delle tracce: ricostruisci i log degli eventi polimorfici in catene causali di eventi per eseguire il debug delle sessioni su più turni, incluse le chiamate nidificate di strumenti e LLM.
  • Valutazione deterministica e semantica: valuta la qualità degli agenti in base a criteri basati su regole, come latenza, numero di turni e tassi di errore, nonché criteri semantici, come correttezza, sentiment e allucinazioni.
  • Corrispondenza delle traiettorie: confronta i percorsi di esecuzione effettivi degli agenti con le traiettorie dorate 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 sugli output degli agenti non deterministici, monitora le distribuzioni delle richieste degli utenti, e rileva la regressione della produzione o la deriva semantica.
  • Memoria degli agenti a lungo termine: fornisci agli agenti il recupero semantico del profilo utente e del contesto tra le sessioni, nonché la memoria episodica consapevole del budget di token archiviata in modo nativo in BigQuery.

Registrare e analizzare l'attività degli agenti

L'integrazione dell'SDK nei flussi di lavoro degli agenti in genere prevede i seguenti passaggi:

  1. Registra le interazioni: collega un plug-in logger (ad esempio BigQueryAgentAnalyticsPlugin in ADK) o un gestore callback nel framework di orchestrazione degli agenti. Quando gli utenti interagiscono con l'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 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 le query a livello di programmazione e gestisce le connessioni attive al database.
    • project_id: l' Google Cloud ID progetto che ospita il set di dati di destinazione.
    • dataset_id: il nome del set di dati BigQuery che memorizza i log.
    • table_id: la tabella specifica che memorizza gli eventi di telemetria (agent_events per impostazione predefinita).

  3. Ricostruisci una traccia di 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 ospita l'albero di intervalli DAG gerarchico collegato causalmente ricostruito di tutte le azioni dell'utente e dell'agente.
    • YOUR_SESSION_ID: l'ID univoco della sessione che vuoi esaminare.

  4. Esegui valutazioni automatizzate: assegna un punteggio a livello di programmazione alle traiettorie delle sessioni o verifica la regressione rispetto a una suite di test dorata:

    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 compilata GraderPipeline strutturata che compone metriche di valutazione eterogenee basate su regole e semantiche.
    • session_ids: l'elenco delle stringhe ID sessione su cui eseguire le valutazioni batch in BigQuery.
    • report: l'oggetto EvaluationReport risultante contenente i punteggi delle sessioni non elaborati, i riepiloghi delle metriche, le statistiche di prova e il feedback del valutatore automatico.

Integrare BigQuery Agent Analytics nel flusso di lavoro

Per integrare BigQuery Agent Analytics nel flusso di lavoro, consulta la documentazione del framework:

Passaggi successivi