Tracciare le decisioni dell'agente AI con BigQuery Graph

1. Introduzione

BigQuery Graph, Analisi conversazionale in BigQuery e BigQuery Agent Analytics SDK sono attualmente in anteprima su Google Cloud. Il plug-in BigQuery Agent Analytics è in disponibilità generale. Gli esempi in questo codelab utilizzano dati sintetici.

Man mano che gli agenti AI autonomi assumono maggiori responsabilità operative (valutazione delle richieste di prestito, gestione dei budget di marketing, approvazione delle richieste di accesso), le organizzazioni devono essere in grado di controllare e spiegare le loro decisioni. Ricostruire il contesto esatto, le alternative prese in considerazione e la logica finale della decisione di un agente è essenziale per la conformità, la gestione del rischio e l'affidabilità operativa.

Questo codelab utilizza l'SDK Analytics di BigQuery Agent per trasformare i log degli eventi dell'agente non elaborati in un grafico del contesto dell'agente, un grafico interrogabile in BigQuery Graph delle decisioni dell'agente, in base a una pianificazione, senza database di grafici esterni o pipeline ETL.

Termini chiave

• Traccia delle decisioni dell'agente: le prove a livello di decisione estratte dalle esecuzioni dell'agente stesso: le opzioni che ha valutato, i dati che ha toccato e il risultato che ha ottenuto.
• Grafico del contesto dell'agente: il grafico digitato e interrogabile in BigQuery Graph in cui vengono materializzate le tracce. Si tratta dell'istanza con ambito agente del concetto di grafico contestuale del settore (il livello durevole e collegato al tempo del contesto decisionale che gli agenti producono e utilizzano); il qualificatore "Agente" lo limita alle esecuzioni dei tuoi agenti anziché a un livello di contesto a livello aziendale.

In questo codelab, bqaa context-graph estrae le tracce delle decisioni dell'agente da agent_events e le materializza in un grafico del contesto dell'agente che puoi interrogare con GQL, seguendo il pattern del settore in cui i grafici del contesto vengono creati a partire dalle tracce delle decisioni.

Cosa creerai

• Un grafico del contesto dell'agente (con BigQuery Graph) che modella un flusso decisionale generico dell'agente: arriva una richiesta, l'agente valuta le opzioni e viene stabilito un risultato.
• Una tabella agent_events compilata con un corpus di eventi sintetici.
• Un'esecuzione bqaa context-graph funzionante che riempie il grafico con questi eventi.
• Una query GQL in stile audit che traccia una singola decisione end-to-end.

Obiettivi didattici

• Come il plug-in BigQuery Agent Analytics scrive in agent_events.
• Come viene definito un grafico contestuale da soli due artefatti dichiarativi: un DDL della tabella e uno schema CREATE PROPERTY GRAPH.
• Come eseguire bqaa context-graph su un grafico BigQuery.
• Come eseguire query su un grafico utilizzando GQL.
• Le funzionalità di livello di produzione supportate dall'SDK per le implementazioni aziendali.

Che cosa ti serve

• Un progetto Google Cloud con la fatturazione abilitata.
• Ruolo Proprietario o Editor per il progetto. Creerai un set di dati BigQuery e concederai IAM.
• L'interfaccia a riga di comando gcloud installata e autenticata o l'accesso a Cloud Shell.
• Python 3.10 o versioni successive.
• Familiarità con BigQuery SQL. Non è richiesta la conoscenza di GQL.

Questo codelab è rivolto a sviluppatori di tutti i livelli, inclusi quelli che non hanno mai utilizzato BigQuery Graph.

Le risorse create in questo codelab costano molto poco e il passaggio finale elimina tutto, in modo che non ti venga addebitato un set di dati inattivo.

Durata stimata:il completamento di questo codelab richiede circa 35 minuti.

2. Prima di iniziare

Scegli un progetto e una regione

Apri Cloud Shell o un terminale locale:

export PROJECT_ID="your-project-id"
export REGION="us-central1"
export DATASET="agent_analytics_demo"
gcloud config set project "$PROJECT_ID"

La singola variabile DATASET contiene sia la tabella agent_events non elaborata sia le tabelle dei grafici materializzati. L'utilizzo di un solo set di dati semplifica il codelab. I deployment di produzione spesso dividono eventi e grafici in set di dati separati, in modo che IAM possa essere concesso in modo specifico per ogni set di dati.

Abilita le API richieste

Esegui il seguente comando per abilitare le API utilizzate in questo codelab:

gcloud services enable \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    --project="$PROJECT_ID"

L'API aiplatform.googleapis.com è necessaria perché il percorso di estrazione predefinito dell'SDK chiama la funzione AI.GENERATE di BigQuery. Se in un secondo momento passi all'estrazione deterministica con --extraction-mode=compiled-only, questa API non è più necessaria.

Crea il set di dati BigQuery

Crea il set di dati che conterrà sia la tabella agent_events non elaborata sia le tabelle del grafico materializzato:

bq --location=US mk --dataset "$PROJECT_ID:$DATASET"

Dovresti visualizzare un messaggio di operazione riuscita:

Dataset 'your-project-id:agent_analytics_demo' successfully created.

Se il set di dati esiste già, il comando genera un errore innocuo. Lascialo in posizione.

3. Installa l'SDK

Configura un ambiente virtuale Python e installa l'SDK da PyPI:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install bigquery-agent-analytics

Il pacchetto bigquery-agent-analytics incorpora la libreria client di BigQuery, quindi questa è l'unica installazione necessaria per l'intero codelab.

Verifica l'installazione:

bqaa context-graph --help | head -8

Dovresti visualizzare il banner della CLI.

Autentica

Se usi una workstation:

gcloud auth login
gcloud auth application-default login

Gli utenti di Cloud Shell possono saltare questo passaggio, poiché le credenziali sono già configurate.

4. Recuperare gli artefatti del codelab

Il codelab richiede solo due artefatti pronti all'uso: il DDL della tabella (le tabelle del grafico fisico) e lo schema del grafico delle proprietà (CREATE PROPERTY GRAPH). Non devi crearli tu stesso; il codelab li utilizza così come sono e il README nella cartella degli artefatti spiega come adattarli al tuo dominio decisionale.

Lo schema del grafico delle proprietà è l'unica fonte di verità per cosa contiene il grafico. Lo applichi a BigQuery una sola volta; da quel momento in poi, il grafico di deployment stesso è il contratto. Quando esegui la materializzazione, bqaa context-graph legge la definizione del grafico da INFORMATION_SCHEMA.PROPERTY_GRAPHS di BigQuery (insieme agli schemi delle tabelle a cui fa riferimento) per capire quali entità e relazioni estrarre e dove scriverle, quindi nessun file SQL viene mai passato al materializzatore.

Questo codelab è autonomo, quindi non devi scaricare nulla. Il comando riportato di seguito scrive il DDL del grafico contestuale in una directory di lavoro. I suoi contenuti sono identici agli artefatti spediti in examples/context_graph/codelab/.

Crea la directory di lavoro:

mkdir -p ~/context-graph-codelab
cd ~/context-graph-codelab

Scrivi il DDL del grafico contestuale (context_graph_ddl.sql). I marcatori ${PROJECT_ID} / ${DATASET} vengono compilati quando applichi il file nel passaggio successivo.

cat > context_graph_ddl.sql <<'SQL'

-- Node and edge table DDL for the context-graph codelab.
--
-- `bqaa context-graph` writes into these tables on every run.
-- `session_id` and `extracted_at` are SDK metadata columns that
-- `bqaa context-graph` fills automatically; they are required on
-- every table behind the graph.
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_request` (
  request_id STRING, request_text STRING, requested_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_option` (
  option_id STRING, option_label STRING, confidence FLOAT64,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_outcome` (
  outcome_id STRING, status STRING, rationale STRING, decided_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.evaluates_option` (
  request_id STRING, option_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.resulted_in` (
  request_id STRING, outcome_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);

-- Graph DDL for the context-graph codelab.
--
-- Models a generic agent decision flow:
--   DecisionRequest -> evaluatesOption -> DecisionOption
--   DecisionRequest -> resultedIn       -> DecisionOutcome
CREATE OR REPLACE PROPERTY GRAPH `${PROJECT_ID}.${DATASET}.agent_decisions_graph`
  NODE TABLES (
    `${PROJECT_ID}.${DATASET}.decision_request` AS decision_request
      KEY (request_id)
      LABEL DecisionRequest PROPERTIES (request_id, request_text, requested_at),
    `${PROJECT_ID}.${DATASET}.decision_option` AS decision_option
      KEY (option_id)
      LABEL DecisionOption PROPERTIES (option_id, option_label, confidence),
    `${PROJECT_ID}.${DATASET}.decision_outcome` AS decision_outcome
      KEY (outcome_id)
      LABEL DecisionOutcome PROPERTIES (outcome_id, status, rationale, decided_at)
  )
  EDGE TABLES (
    `${PROJECT_ID}.${DATASET}.evaluates_option` AS evaluates_option
      KEY (request_id, option_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (option_id) REFERENCES decision_option (option_id)
      LABEL evaluatesOption,
    `${PROJECT_ID}.${DATASET}.resulted_in` AS resulted_in
      KEY (request_id, outcome_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (outcome_id) REFERENCES decision_outcome (outcome_id)
      LABEL resultedIn
  );
SQL

Verifica che il file sia presente:

ls

Dovresti vedere un file:

context_graph_ddl.sql

Il flusso decisionale che descrivono ha tre tipi di nodi e due archi eterogenei:

DecisionRequest è la domanda che ha ricevuto l'agente. DecisionOption è un'alternativa presa in considerazione dall'agente. DecisionOutcome registra la scelta e la motivazione.

5. Applica lo schema del grafico delle proprietà

bqaa context-graph scrive nelle tabelle BigQuery, quindi devono esistere prima della prima esecuzione. context_graph_ddl.sql crea prima le cinque tabelle e poi il grafico delle proprietà che le fa riferimento (BigQuery rifiuta un CREATE PROPERTY GRAPH che punta a tabelle che non esistono ancora), quindi un'unica applicazione configura tutto:

envsubst < context_graph_ddl.sql | bq query --use_legacy_sql=false

Dovresti vedere cinque risultati CREATE TABLE e un risultato CREATE PROPERTY GRAPH. Il DDL è idempotente, quindi puoi eseguirlo di nuovo in modo sicuro.

Questo è l'unico lavoro sullo schema che devi fare e l'unica volta in cui vengono utilizzati questi file SQL. BigQuery ora registra la definizione del grafico e bqaa context-graph la legge da INFORMATION_SCHEMA.PROPERTY_GRAPHS in base al nome. Non esiste un file separato da passare al materializzatore e ciò che viene interrogato con GQL e ciò che viene materializzato non possono mai divergere: si tratta dello stesso grafico di cui è stato eseguito il deployment.

6. Genera eventi dell'agente di esempio

In produzione, il plug-in BigQuery Agent Analytics acquisisce automaticamente gli eventi durante l'esecuzione dell'agente ADK. Questo snippet è solo a scopo di riferimento. Non eseguirlo in questo codelab:

from google.adk.plugins import BigQueryAgentAnalyticsPlugin

plugin = BigQueryAgentAnalyticsPlugin(
    project_id="your-project-id",
    dataset_id="agent_analytics_demo",
)
runner = Runner(agent=root_agent, plugins=[plugin])

Per questo codelab utilizzi un piccolo generatore di eventi sintetici che scrive la stessa forma di righe direttamente in agent_events. Esegui:

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --sessions 5

Il comando stampa un report JSON. Per 5 sessioni dovresti vedere "events_generated": 30, "events_inserted": 30 e "ok": true.

Visualizza l'anteprima del corpus a colpo d'occhio: numero di sessioni, numero di eventi e intervallo di tempo che coprono, in una sola riga:

bq query --use_legacy_sql=false \
    "SELECT COUNT(DISTINCT session_id) AS sessions, COUNT(*) AS events, MIN(timestamp) AS earliest_event, MAX(timestamp) AS latest_event FROM \`$PROJECT_ID.$DATASET.agent_events\`"

Per l'esecuzione predefinita di 5 sessioni, vengono visualizzate 5 sessioni e 30 eventi che si svolgono in pochi minuti. (Inserisci lo scenario realistico riportato di seguito e lo stesso report di query mostra circa 100 sessioni in circa tre giorni.)

Verifica che gli eventi siano stati registrati:

bq query --use_legacy_sql=false \
    "SELECT event_type, COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY event_type ORDER BY n DESC"

Dovresti visualizzare 25 righe TOOL_COMPLETED e 5 righe AGENT_COMPLETED (ogni sessione genera un submit_request, tre evaluate_option, un commit_outcome e un AGENT_COMPLETED di chiusura, ovvero cinque eventi strumento più un terminatore agente per sessione). Le righe AGENT_COMPLETED sono i terminatori di sessione su cui si basa bqaa context-graph per il rilevamento degli eventi terminali.

(Facoltativo) Dati su scala realistica

Il corpus di 5 sessioni riportato sopra è intenzionalmente molto piccolo, in modo che la prima esecuzione sia rapida ed economica. Quando vuoi dati di produzione, ovvero più agenti e utenti distribuiti su più giorni, con sessioni non riuscite, orfane e troncate, utilizza lo scenario decision-realistic. Il valore predefinito è 100 sessioni in un periodo di 72 ore; il percorso della prima esecuzione sopra riportato rimane invariato.

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --scenario decision-realistic \
    --sessions 100 \
    --seed 42

Il report JSON session_outcome_counts mostra la combinazione, ovvero circa {"success": 70, "failed": 10, "orphaned": 10, "truncated": 10}.

Una volta ottenuto questo corpus realistico, la guida Conversational Analytics-first mostra come porre la domanda in inglese semplice ("which requests weighed a low-confidence option?") prima di passare a GQL.

Conferma la distribuzione dei risultati classificando ogni sessione dalle relative righe (orfana = nessun AGENT_COMPLETED; non riuscita = AGENT_COMPLETED con status = 'error'; troncata = qualsiasi riga con is_truncated = true; altrimenti riuscita). Una prima passata classifica ogni sessione, poi una seconda aggrega per risultato:

bq query --use_legacy_sql=false \
    "WITH per_session AS (SELECT session_id, CASE WHEN COUNTIF(event_type = 'AGENT_COMPLETED') = 0 THEN 'orphaned' WHEN COUNTIF(event_type = 'AGENT_COMPLETED' AND status = 'error') > 0 THEN 'failed' WHEN COUNTIF(is_truncated) > 0 THEN 'truncated' ELSE 'success' END AS outcome FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY session_id) SELECT outcome, COUNT(*) AS sessions FROM per_session GROUP BY outcome ORDER BY outcome"

Dovresti visualizzare circa 70 sessioni riuscite, 10 non riuscite, 10 orfane e 10 troncate (più le 5 sessioni riuscite del corpus di prima esecuzione se lo hai inizializzato in precedenza nello stesso set di dati).

Le 10 sessioni orfane non hanno mai emesso AGENT_COMPLETED, quindi l'esecuzione predefinita di bqaa context-graph le salta (materializza solo le sessioni chiuse con evento terminale). Per visualizzarli come session_orphaned anziché riprovare in silenzio per sempre, aggiungi --max-session-age-hours quando lo esegui. Vedi --max-session-age-hours in Passaggio alla produzione.

Questo scenario distribuisce intenzionalmente le sessioni in un periodo di 72 ore. La procedura dettagliata Materializza il grafico contestuale riportata di seguito utilizza --lookback-hours 24 ed è scritta per il piccolo corpus della prima esecuzione di 5 sessioni, quindi i conteggi esatti presuppongono che non tu abbia eseguito questo passaggio facoltativo. Se l'hai fatto, questa è la lezione che volevamo insegnarti: una finestra di materializzazione di 24 ore acquisisce solo la parte recente di un backlog di più giorni. Amplia --lookback-hours per acquisire le sessioni precedenti.

7. Materializzare il grafico contestuale

bqaa context-graph legge agent_events non elaborato, poi deriva cosa estrarre direttamente dal grafico di cui è stato eseguito il deployment: legge la definizione di CREATE PROPERTY GRAPH che hai applicato in Applica lo schema del grafico delle proprietà da INFORMATION_SCHEMA.PROPERTY_GRAPHS di BigQuery, la unisce agli schemi delle tabelle a cui fa riferimento, determina le entità, le relazioni e i tipi di colonne e compila le tabelle del grafico. Lo indirizzi al grafico di cui è stato eseguito il deployment per nome con --graph agent_decisions_graph. Non è necessario passare alcun file SQL.

Corsa

bqaa context-graph localmente:

bqaa context-graph \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --graph agent_decisions_graph \
    --lookback-hours 24 \
    --format json

La prima esecuzione legge ogni evento nella finestra temporale e scrive le tabelle del grafico, pertanto il completamento dell'operazione potrebbe richiedere alcuni minuti.

Dovresti visualizzare un report JSON strutturato:

{
  "run_id": "...",
  "sessions_discovered": 5,
  "sessions_materialized": 5,
  "sessions_failed": 0,
  "rows_materialized": {
    "DecisionRequest": 5,
    "DecisionOption": 15,
    "DecisionOutcome": 5
  },
  "ok": true
}

ok: true indica che bqaa context-graph ha trovato cinque sessioni completate, ha estratto il flusso decisionale da ciascuna tramite AI.GENERATE e ha scritto le righe corrispondenti nelle tabelle del grafico. L'estrazione deterministica (--extraction-mode=compiled-only, descritta di seguito) restituisce la stessa forma del report (stessi campi, stesso ok: true), ma salta le chiamate AI.GENERATE.

Risoluzione dei problemi: estrazione vuota

Se visualizzi ok: false con error_code = "empty_extraction", la causa più comune è che l'API aiplatform.googleapis.com non è ancora stata propagata o che nel tuo account manca roles/aiplatform.user. Attendi un minuto e riprova oppure assegna il ruolo:

USER_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="user:$USER_EMAIL" --role="roles/aiplatform.user"

Quindi, esegui di nuovo il comando bqaa context-graph riportato sopra.

Verifica che il grafico contenga righe:

bq query --use_legacy_sql=false \
    "SELECT COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.decision_request\`"

Dovresti vedere cinque righe. Nelle cinque sessioni, ovvero 25 nodi del grafico in totale (5 DecisionRequest, 15 DecisionOption e 5 DecisionOutcome), uniti da 15 archi evaluatesOption e 5 archi resultedIn (una rete decisionale per sessione).

Due modi per estrarre le decisioni dagli eventi

bqaa context-graph offre due percorsi di estrazione. Scegli quello che corrisponde al tuo carico di lavoro:

• Estrazione predefinita. Il percorso più semplice. Utilizza AI.GENERATE di BigQuery per leggere i contenuti degli eventi e dedurre entità e relazioni. Funziona con qualsiasi forma di evento senza codice aggiuntivo. Questo è ciò che utilizza il codelab.
• Estrazione deterministica (--extraction-mode=compiled-only). Il percorso più economico e adatto ai controlli. Utilizza un piccolo estrattore di riferimenti Python che scrivi una sola volta per il tuo dominio. Nessuna chiamata a Vertex AI, nessun addebito per token, output completamente riproducibile. Le implementazioni di produzione scelgono questa opzione quando la prevedibilità dei costi o la riproducibilità rigorosa sono importanti.

La guida al deployment del grafico contestuale è il riferimento per entrambi i percorsi, inclusi i dettagli IAM e come creare un estrattore di riferimenti.

8. Esegui query sulla traccia della decisione

Una volta compilato il grafico, puoi rispondere direttamente alla domanda di controllo. Prendiamo un esempio concreto: "Per ogni richiesta, quali opzioni ha valutato l'agente e come è stata risolta?" In GQL, si tratta di un singolo attraversamento della richiesta, delle relative opzioni e del relativo risultato.

Scrivi la query in un file (traversal.sql). Il marcatore ${DATASET} viene compilato quando esegui la query nel passaggio successivo:

cat > traversal.sql <<'SQL'
SELECT *
FROM GRAPH_TABLE (
  ${DATASET}.agent_decisions_graph
  MATCH
    (req:DecisionRequest) -[eo:evaluatesOption]-> (opt:DecisionOption),
    (req)                 -[ri:resultedIn]->      (out:DecisionOutcome)
  COLUMNS (
    req.request_id   AS request,
    req.request_text AS question,
    opt.option_label AS considered,
    opt.confidence   AS score,
    out.status       AS outcome,
    out.rationale    AS rationale
  )
);
SQL

Esegui:

envsubst < traversal.sql | bq query --use_legacy_sql=false --max_rows=20

Dovresti vedere quindici righe: tre opzioni per richiesta, cinque richieste. Ogni riga mostra la richiesta, l'opzione presa in considerazione dall'agente, il relativo punteggio di confidenza, il risultato finale e la motivazione.

Per avere un quadro completo di una singola decisione, filtra per request_id per ottenere il set di righe di cui ha bisogno un team di audit: la domanda ricevuta, le opzioni valutate (con i punteggi) e la motivazione fornita.

Visualizzare il grafico in BigQuery Studio

BigQuery Studio può anche visualizzare il grafico. Apri BigQuery Studio nella console BigQuery, esegui la query sul percorso riportata di seguito, quindi passa al riquadro dei risultati nella scheda Grafico per visualizzare il web decisionale. Con il corpus in scala realistica, ottieni una mappa visiva di richieste, opzioni e risultati:

GRAPH agent_analytics_demo.agent_decisions_graph
MATCH p = (a)-[e]->(b)
RETURN TO_JSON(p) AS path_json

La console BigQuery non espande le variabili della shell, quindi incolla il nome del set di dati letterale. Questa query utilizza agent_analytics_demo (il valore DATASET della sezione Prima di iniziare); modificala se hai utilizzato un altro set di dati.

Fai la stessa domanda in inglese semplice

Non tutti i lettori di audit scrivono query GQL. Con BigQuery Conversational Analytics (anteprima), il tuo team di conformità può porre lo stesso tipo di domanda in linguaggio naturale e ricevere una scheda di risposta strutturata, senza sintassi di query e senza join da imparare.

Registra agent_decisions_graph (insieme a agent_events e alle tabelle delle decisioni) come origine dati di Analisi conversazionale, poi poni direttamente la domanda di controllo:

Domanda di audit (in inglese semplice): "Which requests never reached a committed outcome?" (Quali richieste non hanno mai raggiunto un risultato impegnato?)

L'Analisi conversazionale analizza il grafico, scrive il codice SQL per te e risponde in inglese semplice con una tabella di supporto. In questo caso, ogni richiesta registrata ha raggiunto un risultato definitivo:

La risposta riportata sopra riflette il corpus in scala realistica del passaggio facoltativo dati in scala realistica (90 richieste materializzate, tutte confermate); i numeri esatti dipendono dal corpus che hai inserito e dall'esecuzione predefinita di 5 sessioni.

Per la configurazione, consulta la documentazione di Conversational Analytics.

9. Portalo in produzione

L'esecuzione locale riportata sopra utilizza il comportamento predefinito, che copre già le nozioni di base per le implementazioni reali: ogni esecuzione lascia una traccia di controllo (Cloud Logging strutturato più una riga per esecuzione in una tabella di stato nel tuo set di dati), i guasti temporanei vengono ritentati automaticamente e l'avanzamento si verifica solo nelle sessioni completate correttamente, quindi non c'è doppio conteggio.

I controlli di produzione (estrazione deterministica --extraction-mode=compiled-only, rilevamento delle sessioni bloccate --max-session-age-hours, riproduzione una tantum di una finestra precedente --backfill --from / --to, monitorata separatamente dall'aggiornamento regolare in modo che non possa disturbare la programmazione live e delimitazione dei batch per esecuzione --max-sessions) sono flag di attivazione che utilizzi quando ne hai bisogno. La guida al deployment del grafico contestuale documenta ciascuno con la matrice IAM completa e le pianificazioni consigliate.

Da "esegui questa operazione una volta" a "esegui questa operazione ogni sei ore": l'SDK include uno script di deployment e un modulo Terraform che esegue il wrapping di bqaa context-graph come job Cloud Run attivato da Cloud Scheduler, con service account con privilegi minimi e le concessioni IAM necessarie per il job. Segui il runbook di deployment del grafico del contesto dell'agente pianificato per eseguire il deployment pianificato di questo grafico con lo stesso flusso --graph.

10. Esegui la pulizia

Elimina ciò che hai creato per non ricevere addebiti per un set di dati inattivo:

bq rm -r -f --dataset "$PROJECT_ID:$DATASET"

Questo singolo comando rimuove insieme il set di dati, gli eventi dell'agente, le tabelle del grafico e la tabella di stato.

11. Complimenti

Complimenti! Hai trasformato i log degli eventi dell'agente non elaborati in un grafico del contesto dell'agente su cui è possibile eseguire query e hai tracciato una singola decisione end-to-end, senza database grafico esterno o pipeline ETL.

Lo stesso schema si applica ovunque un agente prenda decisioni importanti: sottoscrizione di credito, autorizzazione preventiva, spostamenti del budget di marketing, approvvigionamento, servizio clienti e IT interno. Per creare il tuo grafico del contesto dell'agente, copia gli artefatti del codelab come punto di partenza, adatta i due file dichiarativi (DDL della tabella + schema CREATE PROPERTY GRAPH) al tuo dominio e applicali a BigQuery. bqaa context-graph --graph legge il grafico di nuovo da INFORMATION_SCHEMA e deriva il resto.

Cosa hai imparato

• Come creare un set di dati BigQuery e applicare uno schema di grafici delle proprietà che descrive un dominio di decisione dell'agente.
• Come compilare agent_events con un corpus di eventi sintetici.
• Come eseguire bqaa context-graph per estrarre le tracce delle decisioni dell'agente in un grafico del contesto dell'agente da questi eventi, leggendo la definizione del grafico da INFORMATION_SCHEMA.
• Come eseguire query sul grafico risultante in GQL e leggere la risposta in stile audit.

Documenti di riferimento

• Repository BigQuery SDK Analytics Agent
• Artefatti del codelab e guida all'adattamento
• Guida al deployment del grafico contestuale: API richieste, matrice IAM, pianificazioni consigliate, query di avviso di Cloud Monitoring e modulo Terraform.
• Documentazione di BigQuery Graph (anteprima).
• Documentazione di BigQuery Conversational Analytics (anteprima).