Utilizza BigQuery Agent Analytics

BigQuery Agent Analytics è una soluzione open source che ti consente di acquisire, analizzare e visualizzare i dati delle interazioni degli agenti multimodali su larga scala 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. BigQuery Agent Analytics è supportato 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 (gRPC), che fornisce un flusso di log ad alto throughput e bassa latenza senza bloccare l'esecuzione dell'agente.

Il flusso di dati è costituito dalle seguenti fasi:

  1. Acquisisci. Utilizza un plug-in di logging in ADK o un gestore callback in LangGraph per intercettare e acquisire gli eventi di interazione dell'agente.
  2. Stream. Gli eventi di interazione vengono inviati a BigQuery tramite l'API Storage Write (gRPC). Se non esiste uno schema standardizzato, l'agente ne crea uno automaticamente.
  3. Consuma. Analizza e valuta i dati dell'agente Logging. 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 degli agenti multi-turn complesse.

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

Vantaggi dell'analisi degli agenti

  • Abilita il logging completo con una singola riga di codice e automatizza la gestione dello schema.
  • Registra e analizza 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 predefinito e solido.
  • Identifica le opportunità di ottimizzazione utilizzando le funzioni AI generative e Vector Search di BigQuery.
  • Proteggi i log agentici con controlli degli accessi granulari, mascheramento dei dati e crittografia.

Scegli una libreria per ogni fase del workflow

BigQuery Agent Analytics ha due integrazioni di logging e un SDK Analytics. Le integrazioni di logging e l'SDK Analytics servono diverse fasi del tuo workflow:

  • Registra gli eventi dell'agente Logging: utilizza l'integrazione del logging per il framework dell'agente, il plug-in ADK o il gestore callback LangGraph e LangChain. È sufficiente una sola integrazione di logging e non è necessario l'SDK Analytics per registrare gli eventi. Per altri framework o per attivare il logging delle conversazioni integrato per gli agenti per i dati di analisi conversazionale, consulta Modi per acquisire i dati di log agentico.
  • Analizza gli eventi dell'agente: utilizza l'SDK BigQuery Agent Analytics per eseguire query, ricostruire e valutare gli eventi registrati. Puoi anche analizzare gli eventi con query SQL e dashboard.

Il seguente diagramma mostra quale libreria utilizzare in ogni fase del workflow:

Il plug-in ADK o il gestore callback LangGraph e LangChain trasmette gli eventi dell'agente a una tabella di eventi BigQuery che analizzi con l'SDK Analytics BigQuery Agent Analytics, le query SQL o le dashboard.

La tabella seguente descrive ogni integrazione di logging e l'SDK Analytics:

Fase del workflow Integrazione o SDK Pacchetto e punto di accesso Quando utilizzarla
Eventi dell'agente Logging Plug-in BigQuery Agent Analytics di ADK

Pacchetto Python google-adk[bigquery-analytics]

Classe BigQueryAgentAnalyticsPlugin

Per altri linguaggi, come Java, consulta la guida ai plug-in ADK.

 Utilizzalo in un agente ADK per trasmettere in streaming richieste LLM, chiamate agli strumenti ed eventi del workflow a BigQuery.
Eventi dell'agente Logging Gestore callback BigQuery LangGraph e LangChain (anteprima)

Pacchetto Python langchain-google-community[bigquery]

Classe BigQueryCallbackHandler

 Utilizzalo in un'applicazione LangGraph o LangChain per trasmettere in streaming gli eventi di esecuzione dell'agente a BigQuery.
Analizza gli eventi dell'agente SDK BigQuery Agent Analytics

Pacchetto Python bigquery-agent-analytics

Client e GraderPipeline corso

 Utilizzala in pipeline di valutazione, notebook o servizi di controllo per leggere la tabella degli eventi in cui scrive l'integrazione del logging, ricostruire sessioni multi-turn ed eseguire valutazioni automatiche.

Modi per acquisire i dati dei log degli agenti

Per acquisire la telemetria delle interazioni dell'agente (richieste, risposte, chiamate agli strumenti e log degli errori) in modo nativo in BigQuery, puoi registrare i dati sugli 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 ADK si aggancia all' esecutore dell'agente per intercettare, serializzare e trasmettere automaticamente gli eventi.
  • Gestori callback del framework: integra i callback standard negli ambienti degli agenti più diffusi. Ad esempio, puoi utilizzare BigQueryCallbackHandler del pacchetto langchain-google-community in LangGraph e LangChain per intercettare e inoltrare le tracce a BigQuery.
  • Importazione diretta dell'API: per i 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 (gRPC).
  • Agenti di dati di analisi conversazionale: attiva il logging delle conversazioni integrato quando configuri le impostazioni per un agente di dati BigQuery in BigQuery Studio o tramite l'API Conversational Analytics per trasmettere automaticamente in streaming gli eventi di conversazione a una tabella BigQuery di destinazione e analizzare i log delle conversazioni.

Indipendentemente dal metodo, tutte le opzioni di logging utilizzano l'API BigQuery Storage Write (gRPC) a bassa latenza e con throughput elevato. Questa API fornisce un endpoint di streaming affidabile 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 le prestazioni dell'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 join con tabelle aziendali per misurare l'impatto sull'attività.
  • Dashboard interattive: collega strumenti di visualizzazione come Data Studio a visualizzazioni BigQuery predefinite o personalizzate per monitorare l'integrità degli agenti, i tassi di errore e le tendenze di utilizzo nel tempo. I clienti di Looker possono anche utilizzare un modello di dashboard di BigQuery Agent Analytics predefinito (blocco Looker) dal Looker Marketplace.
  • 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 le tracce di esecuzione degli agenti in modo programmatico direttamente nel codice dell'applicazione o nelle pipeline di valutazione automatizzate.

Esempi di utilizzo dei dati di log agentico

Di seguito sono riportati esempi e casi d'uso comuni di utilizzo dei dati dei log agentici in BigQuery.

Osservabilità e metriche operative

  • 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 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 il ranking 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, quindi confrontali con l'intent originale dell'utente. In questo modo puoi identificare le lacune negli strumenti o nella knowledge base dell'agente.

Insight e contestualizzazione aziendali

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 le formule di query.

Utilizza un notebook Jupyter per lavorare con i log agentici

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

Utilizza 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, mentre 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 Analytics di BigQuery Agent. Per esempi dettagliati di analisi dei log, consulta il repository GitHub per l'SDK.

  • Ricostruzione delle tracce: ricostruisci i log eventi polimorfici in catene causali di eventi per eseguire il debug delle sessioni in più turni, incluse le chiamate a strumenti e LLM nidificate.
  • 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é criteri semantici, come correttezza, sentiment e allucinazioni.
  • Corrispondenza delle traiettorie: confronta i percorsi di esecuzione effettivi dell'agente con le traiettorie ideali previste per verificare l'efficienza dei passaggi e se gli strumenti sono stati utilizzati nell'ordine corretto.
  • Monitoraggio del comportamento e rilevamento della deviazione: esegui analisi statistiche sugli output degli agenti non deterministici, monitora le distribuzioni delle richieste degli utenti e rileva la regressione della produzione o la deviazione semantica.
  • Memoria degli agenti a lungo termine: fornisci agli agenti un contesto tra sessioni, un recupero semantico del profilo utente e una memoria episodica con un budget di token archiviata in modo nativo in BigQuery.

Registra e analizza l'attività degli agenti

L'SDK legge e valuta gli eventi scritti da un'integrazione di logging. Un flusso di lavoro tipico prevede i seguenti passaggi:

  1. Registra le interazioni: nel framework di orchestrazione degli agenti, collega un'integrazione di logging, come BigQueryAgentAnalyticsPlugin in ADK o BigQueryCallbackHandler in LangGraph. Quando gli utenti interagiscono con l'agente, l'integrazione trasmette gli eventi in modo asincrono a BigQuery utilizzando l'API Storage Write (gRPC) ad alta velocità effettiva. Questo passaggio non richiede l'SDK.

  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 indirizza le query in modo programmatico e gestisce le connessioni attive al database.
    • project_id: l'ID progetto Google Cloud che contiene il set di dati di destinazione.
    • dataset_id: il nome del set di dati BigQuery in cui sono archiviati i log.
    • table_id: la tabella in cui sono archiviati gli eventi registrati (agent_events per impostazione predefinita). Questo valore deve corrispondere alla tabella in cui scrive l'integrazione del logging. Ad esempio, BigQueryCallbackHandler nella versione 4.0.0 e precedenti di langchain-google-community scrive in agent_events_v2 per impostazione predefinita.

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

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

    Lo snippet utilizza i seguenti componenti:

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

  4. Esegui valutazioni automatiche: assegna un punteggio alle traiettorie delle sessioni in modo programmatico o verifica la presenza di regressioni rispetto a una suite di test di riferimento:

    from bigquery_agent_analytics import (
    LLMAsJudge,
    TraceFilter,
)

# Run semantic evaluations across target sessions
evaluator = LLMAsJudge.correctness()
filters = TraceFilter(session_ids=["session_1", "session_2"])

report = client.evaluate(evaluator, filters=filters)
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    Lo snippet utilizza i seguenti componenti:

    • evaluator: l'analizzatore semantico (LLMAsJudge) utilizzato per valutare le sessioni (puoi anche eseguire controlli SystemEvaluator basati su regole o combinare gli analizzatori in un GraderPipeline ponderato).
    • filters: l'istanza TraceFilter che specifica l'elenco session_ids (o la finestra temporale e i filtri degli agenti) in base ai quali eseguire le valutazioni batch in BigQuery.
    • report: l'oggetto EvaluationReport risultante contenente i voti della sessione non elaborati, i riepiloghi delle metriche e il feedback del valutatore automatico.

Integra BigQuery Agent Analytics nel tuo workflow

Per integrare BigQuery Agent Analytics nel tuo flusso di lavoro, segui questi passaggi:

  1. Configura l'integrazione del logging per il framework dell'agente:

  2. Analizza gli eventi registrati con l'SDK Analytics di BigQuery Agent, il notebook di Colab di esempio o le formule di query SQL.

Passaggi successivi