Suivre les décisions des agents d'IA avec BigQuery Graph

1. Introduction

BigQuery Graph, BigQuery Conversational Analytics et le SDK BigQuery Agent Analytics sont actuellement en aperçu sur Google Cloud. Le plug-in BigQuery Agent Analytics est en phase de disponibilité générale. Les exemples de cet atelier de programmation utilisent des données synthétiques.

À mesure que les agents d'IA autonomes assument davantage de responsabilités opérationnelles (évaluation des demandes de prêt, gestion des budgets marketing, approbation des demandes d'accès), les organisations doivent être en mesure d'auditer et d'expliquer leurs décisions. Reconstituer le contexte exact, les alternatives envisagées et la justification finale de la décision d'un agent est essentiel pour la conformité, la gestion des risques et la confiance opérationnelle.

Cet atelier de programmation utilise le SDK BigQuery Agent Analytics pour transformer les journaux d'événements d'agent bruts en graphique de contexte d'agent (un graphique interrogeable dans BigQuery Graph des décisions d'agent) selon une planification, sans base de données graphique ni pipeline ETL externes.

Termes clés

• Trace de décision de l'agent : preuves au niveau de la décision extraites des propres exécutions d'un agent (les options qu'il a examinées, les données qu'il a traitées et le résultat qu'il a choisi).
• Graphique contextuel de l'agent : graphique typé et interrogeable dans BigQuery Graph dans lequel ces traces sont matérialisées. Il s'agit de l'instance à portée d'agent du concept de graphique de contexte du secteur (la couche durable et temporelle de contexte de décision que les agents produisent et consomment). Le qualificatif "Agent" le limite aux exécutions de vos propres agents plutôt qu'à une couche de contexte à l'échelle de l'entreprise.

Dans cet atelier de programmation, bqaa context-graph extrait les traces de décision de l'agent de votre agent_events et les matérialise dans un graphique de contexte d'agent que vous pouvez interroger avec GQL. Il suit ainsi le modèle du secteur où les graphiques de contexte sont créés à partir de traces de décision.

Ce que vous allez faire

• Un graphique de contexte d'agent (avec BigQuery Graph) qui modélise un flux de décision d'agent générique : une requête est reçue, l'agent évalue les options et un résultat est validé.
• Table agent_events remplie avec un corpus d'événements synthétiques.
• Exécution bqaa context-graph fonctionnelle qui remplit le graphique à partir de ces événements.
• Requête GQL de type audit qui retrace une décision unique de bout en bout.

Points abordés

• Comment le plug-in BigQuery Agent Analytics écrit-il dans agent_events ?
• Découvrez comment un graphique de contexte est défini par seulement deux artefacts déclaratifs : un DDL de table et un schéma CREATE PROPERTY GRAPH.
• Comment exécuter bqaa context-graph sur un graphique BigQuery
• Découvrez comment interroger un graphique à l'aide de GQL.
• Fonctionnalités de niveau production compatibles avec le SDK pour les déploiements Enterprise.

Prérequis

• Un projet Google Cloud avec facturation activée.
• Rôle de propriétaire ou d'éditeur pour ce projet Vous allez créer un ensemble de données BigQuery et accorder des autorisations IAM.
• La CLI gcloud est installée et authentifiée, ou vous avez accès à Cloud Shell.
• Python 3.10 ou version ultérieure.
• Vous maîtrisez BigQuery SQL. Aucune connaissance de GQL n'est requise.

Cet atelier de programmation s'adresse aux développeurs de tous niveaux, y compris à ceux qui débutent avec BigQuery Graph.

Les ressources créées dans cet atelier de programmation coûtent très peu cher. L'étape finale consiste à tout supprimer pour que vous ne soyez pas facturé pour un ensemble de données inactif.

Durée estimée : Cet atelier de programmation prend environ 35 minutes.

2. Avant de commencer

Choisir un projet et une région

Ouvrez Cloud Shell ou un terminal local :

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

La variable DATASET unique contient à la fois la table agent_events brute et les tables de graphiques matérialisés. L'utilisation d'un seul ensemble de données permet de simplifier l'atelier de programmation. Les déploiements de production divisent souvent les événements et le graphique en ensembles de données distincts afin que IAM puisse être accordé de manière précise par ensemble de données.

Activer les API requises

Exécutez la commande suivante pour activer les API utilisées par cet atelier de programmation :

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

L'API aiplatform.googleapis.com est requise, car le chemin d'extraction par défaut du SDK appelle la fonction AI.GENERATE de BigQuery. Si vous passez ensuite à l'extraction déterministe avec --extraction-mode=compiled-only, cette API n'est plus nécessaire.

Créer l'ensemble de données BigQuery

Créez l'ensemble de données qui contiendra à la fois la table agent_events brute et les tables de graphiques matérialisés :

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

Un message confirmant le succès de l'opération doit s'afficher :

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

Si l'ensemble de données existe déjà, la commande génère une erreur inoffensive. Laissez-le en place.

3. Installer le SDK

Configurez un environnement virtuel Python et installez le SDK à partir de PyPI :

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

Le package bigquery-agent-analytics extrait la bibliothèque cliente BigQuery. Il s'agit donc de la seule installation dont vous avez besoin pour l'ensemble de l'atelier de programmation.

Vérifiez l'installation :

bqaa context-graph --help | head -8

La bannière CLI devrait s'afficher.

Authentifier

Si vous utilisez un poste de travail :

gcloud auth login
gcloud auth application-default login

Les utilisateurs de Cloud Shell peuvent ignorer cette étape, car les identifiants sont déjà configurés.

4. Obtenir les artefacts de l'atelier de programmation

L'atelier de programmation n'a besoin que de deux artefacts prêts à l'emploi : le DDL de table (tables de graphiques physiques) et le schéma de graphique de propriétés (CREATE PROPERTY GRAPH). Vous n'avez pas besoin de les créer vous-même. L'atelier de programmation les utilise tels quels, et le fichier README du dossier d'artefacts explique comment les adapter à votre propre domaine de décision.

Le schéma du graphique de propriété est la seule source fiable pour ce que contient le graphique. Vous l'appliquez à BigQuery une seule fois. À partir de ce moment, le graphique déployé lui-même constitue le contrat. Lorsque vous matérialisez, bqaa context-graph relit la définition du graphique à partir de INFORMATION_SCHEMA.PROPERTY_GRAPHS de BigQuery (ainsi que les schémas des tables auxquelles il fait référence) pour déterminer les entités et les relations à extraire et où les écrire. Aucun fichier SQL n'est donc transmis au matérialisateur.

Cet atelier de programmation est autonome. Vous n'avez donc rien à télécharger. La commande ci-dessous écrit le DDL du graphique de contexte dans un répertoire de travail. Son contenu est identique aux artefacts fournis dans examples/context_graph/codelab/.

Créez le répertoire de travail :

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

Écrivez le LDD du graphique de contexte (context_graph_ddl.sql). Les marqueurs ${PROJECT_ID} / ${DATASET} sont renseignés lorsque vous appliquez le fichier à l'étape suivante.

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

Vérifiez que le fichier est en place :

ls

Un fichier devrait s'afficher :

context_graph_ddl.sql

Le flux de décision qu'ils décrivent comporte trois types de nœuds et deux arêtes hétérogènes :

DecisionRequest correspond à la question reçue par l'agent. DecisionOption est une alternative envisagée par l'agent. DecisionOutcome enregistre le choix effectué et la justification.

5. Appliquer le schéma du graphe de propriété

Les bqaa context-graph écrivent dans des tables BigQuery. Celles-ci doivent donc exister avant la première exécution. context_graph_ddl.sql crée d'abord les cinq tables, puis le graphique de propriété qui les référence (BigQuery rejette un CREATE PROPERTY GRAPH qui pointe vers des tables qui n'existent pas encore). Par conséquent, une seule application suffit pour tout configurer :

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

Vous devriez obtenir cinq résultats CREATE TABLE et un résultat CREATE PROPERTY GRAPH. Le LDD est idempotent. Vous pouvez l'exécuter à nouveau en toute sécurité.

C'est la seule fois où vous travaillez sur le schéma et où ces fichiers SQL sont utilisés. BigQuery enregistre désormais la définition de votre graphique, et bqaa context-graph la relit à partir de INFORMATION_SCHEMA.PROPERTY_GRAPHS par nom. Il n'y a pas de fichier distinct à transmettre au matérialisateur. De plus, ce que vous interrogez avec GQL et ce qui est matérialisé ne peuvent jamais diverger : il s'agit du même graphique déployé.

6. Générer des exemples d'événements d'agent

En production, le plug-in BigQuery Agent Analytics capture automatiquement les événements lorsque votre agent ADK s'exécute. Cet extrait est fourni à titre de référence uniquement. Vous ne l'exécuterez pas dans cet atelier de programmation :

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])

Pour cet atelier de programmation, vous utiliserez un petit générateur d'événements synthétiques qui écrit la même forme de lignes directement dans agent_events. Exécutez l'agent :

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

La commande imprime un rapport JSON. Pour cinq sessions, vous devriez voir "events_generated": 30, "events_inserted": 30 et "ok": true.

Prévisualisez le corpus en un coup d'œil (nombre de sessions, nombre d'événements et période qu'ils couvrent) sur une seule ligne :

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\`"

Pour l'exécution par défaut de cinq sessions, cela affiche cinq sessions et 30 événements répartis sur quelques minutes. (Amorcez le scénario réaliste ci-dessous et la même requête génère environ 100 sessions sur trois jours.)

Vérifiez que les événements ont bien été enregistrés :

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"

Vous devriez voir 25 lignes TOOL_COMPLETED et 5 lignes AGENT_COMPLETED (chaque session émet un submit_request, trois evaluate_option, un commit_outcome et un AGENT_COMPLETED de clôture, soit cinq événements d'outil plus un terminateur d'agent par session). Les lignes AGENT_COMPLETED sont les terminateurs de session sur lesquels bqaa context-graph s'appuie pour la détection des événements de fin.

Facultatif : données à l'échelle réaliste

Le corpus de cinq sessions ci-dessus est volontairement minuscule pour que la première exécution soit rapide et peu coûteuse. Si vous souhaitez obtenir des données de production (plusieurs agents et utilisateurs répartis sur plusieurs jours, avec des sessions ayant échoué, orphelines et tronquées), utilisez le scénario decision-realistic. Par défaut, la limite est de 100 sessions sur une période de 72 heures. Le chemin de la première exécution ci-dessus reste inchangé.

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

Le session_outcome_counts du rapport JSON indique la répartition, soit environ {"success": 70, "failed": 10, "orphaned": 10, "truncated": 10}.

Une fois que vous disposez de ce corpus réaliste, le guide "Conversational Analytics-first" vous montre comment poser des questions en langage naturel ("quelles demandes ont suggéré une option à faible confiance ?") avant de passer au GQL.

Confirmez la distribution des résultats en classant chaque session à partir de ses lignes (orpheline = pas de AGENT_COMPLETED ; échec = AGENT_COMPLETED avec status = 'error' ; tronquée = n'importe quelle ligne avec is_truncated = true ; sinon, succès). Une première passe classe chaque session, puis une seconde agrège les résultats :

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"

Vous devriez voir environ 70 réussites, 10 échecs, 10 orphelins et 10 tronqués (plus les 5 sessions réussies du corpus de première exécution si vous l'avez amorcé plus tôt dans le même ensemble de données).

Les 10 sessions orphelines n'ont jamais émis AGENT_COMPLETED. L'exécution bqaa context-graph par défaut les ignore donc (elle ne matérialise que les sessions fermées par un événement terminal). Pour les afficher sous la forme session_orphaned au lieu de réessayer indéfiniment en mode silencieux, ajoutez --max-session-age-hours lorsque vous l'exécutez. Pour en savoir plus, consultez --max-session-age-hours dans Passer à la production.

Dans ce scénario, les sessions sont volontairement réparties sur une période de 72 heures. La procédure pas à pas Matérialiser le graphique contextuel ci-dessous utilise --lookback-hours 24 et est écrite pour le petit corpus de première exécution de cinq sessions. Par conséquent, ses nombres exacts supposent que vous n'avez pas exécuté cette étape facultative. Si c'est le cas, c'est la leçon à retenir : une fenêtre de matérialisation de 24 heures ne récupère que la tranche récente d'un backlog de plusieurs jours. Élargissez --lookback-hours pour capturer les sessions plus anciennes.

7. Matérialiser le graphique contextuel

bqaa context-graph lit les agent_events brutes, puis détermine ce qu'il faut extraire directement à partir de votre graphique déployé : il relit la définition CREATE PROPERTY GRAPH que vous avez appliquée dans Appliquer le schéma du graphique de propriétés à partir de INFORMATION_SCHEMA.PROPERTY_GRAPHS de BigQuery, la joint aux schémas des tables auxquelles elle fait référence, détermine les entités, les relations et les types de colonnes, puis remplit les tables du graphique. Vous pointez vers le graphique déployé par son nom avec --graph agent_decisions_graph. Il n'y a pas de fichier SQL à transmettre.

Exécuter

bqaa context-graph localement :

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

La première exécution lit chaque événement dans la période d'analyse et écrit les tables de graphiques. Cette opération peut donc prendre quelques minutes.

Vous devriez obtenir un rapport JSON structuré :

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

ok: true indique que bqaa context-graph a trouvé cinq sessions terminées, extrait le flux de décision de chacune d'elles via AI.GENERATE et écrit les lignes correspondantes dans les tables du graphique. L'extraction déterministe (--extraction-mode=compiled-only, voir ci-dessous) renvoie la même forme de rapport (mêmes champs, même ok: true), mais ignore les appels AI.GENERATE.

Dépannage : extraction vide

Si vous voyez ok: false avec error_code = "empty_extraction", la cause la plus fréquente est que l'API aiplatform.googleapis.com ne s'est pas encore propagée ou que votre compte ne dispose pas de roles/aiplatform.user. Patientez une minute, puis réessayez ou accordez le rôle :

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"

Ensuite, exécutez à nouveau la commande bqaa context-graph ci-dessus.

Vérifiez que le graphique comporte des lignes :

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

Cinq lignes devraient s'afficher. Au total, cela représente 25 nœuds de graphe (5 DecisionRequest, 15 DecisionOption et 5 DecisionOutcome), auxquels s'ajoutent 15 arêtes evaluatesOption et 5 arêtes resultedIn (un réseau de décision par session).

Deux façons d'extraire des décisions à partir d'événements

bqaa context-graph propose deux chemins d'extraction. Choisissez celui qui correspond à votre charge de travail :

• Extraction par défaut : Le chemin le plus simple. Utilise AI.GENERATE de BigQuery pour lire le contenu des événements et en déduire les entités et les relations. Fonctionne avec n'importe quelle forme d'événement sans code supplémentaire. C'est ce que l'atelier de programmation utilise.
• Extraction déterministe (--extraction-mode=compiled-only) : l'option la moins chère et la plus adaptée aux audits. Utilise un petit extracteur de références Python que vous écrivez une seule fois pour votre domaine. Aucun appel Vertex AI, aucun frais par jeton, sortie entièrement reproductible. Choisissez cette option pour les déploiements en production lorsque la prévisibilité des coûts ou la reproductibilité stricte sont importantes.

Le guide de déploiement du graphique contextuel est la référence pour les deux chemins d'accès, y compris les détails IAM et la façon de créer un extracteur de références.

8. Interroger la trace de décision

Une fois le graphique rempli, vous pouvez répondre directement à la question d'audit. Posez une question concrète : "Pour chaque demande, quelles options l'agent a-t-il envisagées et comment a-t-il résolu le problème ?" Dans GQL, il s'agit d'une seule traversée de la requête, de ses options et de son résultat.

Écrivez la requête dans un fichier (traversal.sql). Le marqueur ${DATASET} est rempli lorsque vous l'exécutez à l'étape suivante :

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

Exécuter l'application :

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

Vous devriez voir quinze lignes : trois options par requête, cinq requêtes. Chaque ligne indique la demande, l'option envisagée par l'agent, son score de confiance, le résultat final et la justification.

Pour obtenir une vue complète d'une décision unique, filtrez par request_id afin d'obtenir l'ensemble de lignes dont une équipe d'audit a besoin : la question posée, les options évaluées (avec les scores) et la justification fournie.

Visualiser le graphique dans BigQuery Studio

BigQuery Studio peut également afficher le graphique visuellement. Ouvrez BigQuery Studio dans la console BigQuery, exécutez la requête de chemin d'accès ci-dessous, puis passez au volet des résultats et à l'onglet Graphique pour afficher le réseau de décision. Avec le corpus à l'échelle réaliste, vous obtenez une carte visuelle des requêtes, des options et des résultats :

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

La console BigQuery ne développe pas les variables shell. Collez donc le nom de l'ensemble de données littéral. Cette requête utilise agent_analytics_demo (la valeur DATASET de la section Avant de commencer). Modifiez-la si vous avez utilisé un autre ensemble de données.

Poser la même question en langage courant

Tous les lecteurs d'audit n'écrivent pas de requêtes GQL. Avec l'analyse conversationnelle BigQuery (version bêta), votre équipe de conformité peut poser le même type de question en langage naturel et obtenir une fiche de réponse structurée. Elle n'a pas besoin d'apprendre la syntaxe des requêtes ni les jointures.

Enregistrez le agent_decisions_graph (ainsi que les tables de décision et agent_events) en tant que source de données Conversational Analytics, puis posez directement la question d'audit :

Question d'audit (en langage naturel)  : "Quelles demandes n'ont jamais abouti à un résultat engagé ?"

L'analyse conversationnelle raisonne sur le graphique, écrit le code SQL pour vous et répond en langage clair avec un tableau d'appui. Ici, chaque demande enregistrée a abouti à un résultat engagé :

La réponse ci-dessus reflète le corpus à l'échelle réaliste de l'étape facultative realistic-scale data (90 demandes concrétisées, toutes validées). Vos chiffres exacts dépendent du corpus que vous avez initialisé. L'exécution par défaut de cinq sessions en affiche cinq.

Pour la configuration, consultez la documentation Conversational Analytics.

9. Passer en production

L'exécution locale ci-dessus utilise le comportement par défaut, qui couvre déjà les bases des déploiements réels : chaque exécution laisse une piste d'audit (journalisation Cloud structurée plus une ligne par exécution dans une table d'état de votre ensemble de données), les échecs temporaires sont automatiquement réessayés et la progression n'avance que sur les sessions entièrement réussies, il n'y a donc pas de double comptabilisation.

Les contrôles de production (extraction déterministe --extraction-mode=compiled-only, détection des sessions bloquées --max-session-age-hours, relecture ponctuelle d'une fenêtre précédente --backfill --from / --to, suivie séparément de l'actualisation régulière afin de ne pas perturber la programmation en direct, et limites de batch par exécution --max-sessions) sont des indicateurs que vous pouvez activer lorsque vous en avez besoin. Le guide de déploiement du graphique de contexte documente chacun d'eux avec la matrice IAM complète et les plannings recommandés.

De "exécuter une fois" à "exécuter toutes les six heures" : le SDK fournit un script de déploiement et un module Terraform qui encapsulent bqaa context-graph en tant que job Cloud Run déclenché par Cloud Scheduler, avec des comptes de service à privilèges minimum et les autorisations IAM dont le job a besoin. Suivez le runbook de déploiement planifié du graphique de contexte de l'agent pour déployer ce graphique de manière planifiée avec le même flux --graph.

10. Effectuer un nettoyage

Supprimez ce que vous avez créé pour ne pas être facturé pour un ensemble de données inactif :

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

Cette commande unique supprime l'ensemble de données, les événements d'agent, les tables de graphiques et la table d'état.

11. Félicitations

Félicitations ! Vous avez transformé les journaux d'événements bruts de l'agent en un graphique contextuel d'agent interrogeable et vous avez suivi une décision unique de bout en bout, sans base de données de graphes externe ni pipeline ETL.

Le même schéma s'applique partout où un agent prend des décisions importantes : souscription de crédit, autorisation préalable, mouvements de budget marketing, achats, service client et informatique interne. Pour créer votre propre graphique de contexte d'agent, copiez les artefacts du tutoriel comme point de départ, adaptez les deux fichiers déclaratifs (DDL de table + schéma CREATE PROPERTY GRAPH) à votre domaine et appliquez-les à BigQuery. bqaa context-graph --graph relit le graphique déployé à partir de INFORMATION_SCHEMA et en déduit le reste.

Connaissances acquises

• Comment créer un ensemble de données BigQuery et appliquer un schéma de graphique de propriété décrivant un domaine de décision d'agent.
• Comment remplir agent_events avec un corpus d'événements synthétiques.
• Comment exécuter bqaa context-graph pour extraire les traces de décision de l'agent dans un graphique de contexte d'agent à partir de ces événements, en relisant la définition du graphique à partir de INFORMATION_SCHEMA.
• Comment interroger le graphique obtenu dans GQL et lire la réponse de type audit.

Documents de référence

• Dépôt du SDK BigQuery Agent Analytics
• Artefacts de l'atelier de programmation et guide d'adaptation
• Guide de déploiement du graphique de contexte : API requises, matrice IAM, plannings recommandés, requêtes d'alerte Cloud Monitoring et module Terraform.
• Documentation BigQuery Graph (aperçu)
• Documentation BigQuery Conversational Analytics (aperçu)