Unboxing the AI Agent: Decision Lineage with BigQuery Context Graphs

[haiyuan-eng-google]

Demo Title: Unboxing the AI Agent: Decision Lineage with BigQuery Context Graphs
Target Duration: 3-4 minutes
Focus: BigQuery Property Graphs, GQL, and Decision Semantics for Yahoo's buyer-side agent.

Phase 1: The Graph Schema in BigQuery Studio (45 seconds)

(Matches step a: Visually showing the shape of the context graph)

• Action: Open BigQuery Studio and display the visual representation or DDL of the 6-Pillar Property Graph.
• Talk Track: "Today, enterprise AI agents are often black boxes. We are going to show how we track every decision a Yahoo buyer-side agent makes using a Context Graph. Here in BigQuery Studio, you can see our graph schema natively models Decision Semantics. Instead of flat event logs, the graph explicitly connects a DecisionPoint to the Candidate options evaluated, assigning a Score and SelectionOutcome. Crucially, it models the RejectionReason, ContextSnapshot, and ConstraintApplication. This forms a complete, EU-compliant audit trail."

Phase 2: Agent Execution & Background Ingestion (30 seconds)

(Matches step b: Running the BQAA plugin on a simulated Yahoo agent)

• Action: Execute a simulated ADCP (Ad Context Protocol) campaign brief in the terminal or UI (e.g., "Launch a $50k brand awareness campaign targeting Gen Z").
• Talk Track: "We are now triggering a simulated Yahoo buyer-side agent to negotiate an ad buy. As the agent plans the campaign, the BigQuery Agent Analytics (BQAA) plugin asynchronously streams the execution telemetry into BigQuery. Behind the scenes, we use AI.GENERATE with a strict JSON output_schema to automatically extract the agent's unstructured reasoning into typed decision nodes and edges, populating the context graph in real-time."

Phase 3: Conversational Analytics & GQL Reasoning (90 seconds)

(Matches step c: Asking business questions and retrieving decision traces)

• Action: Open Conversational Analytics (CA) in BigQuery or the interactive query explorer. Ask business questions to trace the decision.
• Question 1: "Which ad candidates were considered for the Nike campaign, and why were the others rejected?"
• Visual/Query: Show the system translating this into a native GQL traversal query:

  GRAPH `project.dataset.agent_context_graph`
  MATCH (dp:DecisionPoint)-[ce:CandidateEdge]->(cand:CandidateNode)
  WHERE dp.session_id = 'sess-nike-summer' AND ce.edge_type = 'DROPPED_CANDIDATE'
  RETURN cand.name, cand.score, cand.rejection_rationale

• Talk Track: "Using GQL, we can traverse the graph to answer exactly why the agent acted the way it did. The results show that while the agent selected 'Athletes 18-35', it explicitly dropped 'Fitness Enthusiasts' due to 'Budget constraints'. It tells us exactly why we sold to one target instead of another."

Phase 4: Operations Research & Optimization (Bonus) (45 seconds)

(Matches step d: Where can we do better in this bidding process?)

• Action: Pivot to an aggregated dashboard or analytical query summarizing RejectionReason nodes across thousands of sessions.
• Talk Track: "Because these decisions are modeled as a graph, we can move from reactive auditing to proactive Operations Research. If we ask, 'Where can we do better in this bidding process?', we can aggregate the RejectionReason nodes across the graph. If we see a massive cluster of dropped candidates due to 'floor price exceeded', it alerts our yield operations team that our pricing may be misaligned with current market demand. This closes the loop—allowing us to continuously optimize agent actions and update our business constraints based on real-world outcomes."

[caohy1988]

Cross-checked the plan against current main (6656200). The decision-lineage story is real — the SDK ships DecisionPoint, CandidateNode, the MadeDecision/CandidateEdge graph, ContextGraphManager.extract_decision_points(), the EU-audit + dropped-candidate GQL templates, and the world-change drift surface. Most of the demo can run end-to-end on what's already merged. But several talk-track claims overstate what the SDK actually models, and a few phases lack the concrete commands a presenter needs. Below is a phase-by-phase rewrite that keeps the narrative arc but pins it to the real API.

What lines up with the actual code

Demo claim	Real SDK surface	Where
"6-Pillar Property Graph"	4 node types (TechNode, BizNode, DecisionPoint, CandidateNode) + 4 edge types (Caused, Evaluated, MadeDecision, CandidateEdge)	context_graph.py:835-915
AI.GENERATE with strict JSON output_schema extracting decisions	extract_decision_points(use_ai_generate=True) uses _DECISION_POINT_OUTPUT_SCHEMA server-side	context_graph.py:1901
GQL traversal for "which candidates considered, which rejected, why"	get_dropped_candidates_gql() and get_eu_audit_gql() ship pre-canned templates	context_graph.py:2285, 2323
BQAA plugin streams telemetry into BigQuery while the agent runs	Plugin path is real; SDK reads what plugin wrote	(separate package, plugin side)

What overstates the schema (Phase 1 — most important to fix)

The talk track says the graph models RejectionReason, ContextSnapshot, and ConstraintApplication as first-class concepts. None of those exist as schema nodes. What's actually there:

• RejectionReason → a property on CandidateNode: rejection_rationale: STRING (context_graph.py:113-160). Not a node, not its own edge.
• ContextSnapshot → not in the schema at all. The closest thing is BizNode rows that capture the business entities the agent evaluated, but they're not snapshots in the temporal sense.
• ConstraintApplication → not in the schema. Constraint usage shows up implicitly in CandidateNode.score and rejection_rationale text.
• "6-Pillar" → 4 node types + 4 edge types = 8. Or, if you count node types only, 4. Neither comes to 6.

The talk track for Phase 1 needs to either rename to match (e.g., "4-node decision-lineage graph: events, business entities, decisions, candidates") or the schema needs to grow real ContextSnapshot and ConstraintApplication node tables before the demo. The latter is a real PR; the former is a one-line edit. Pick one.

Also the GQL example in Phase 3 has a small error: [ce:CandidateEdge]-> should match the actual schema's source/destination convention. The shipped query uses (dp:DecisionPoint)-[ce:CandidateEdge]->(cand:CandidateNode) which the demo plan got right — but the EU audit traversal is (step:TechNode)-[md:MadeDecision]->(dp:DecisionPoint)-[ce:CandidateEdge]->(cand:CandidateNode), three hops, which is the more compelling demo because it shows which span made each decision. Worth using that one.

Concrete commands per phase

Phase 1 (45s) — graph schema

Replace "open BigQuery Studio and display the visual representation or DDL of the 6-Pillar Property Graph" with a runnable command:

from bigquery_agent_analytics import Client

client = Client(project_id="...", dataset_id="agent_analytics")
mgr = client.context_graph()
print(mgr.get_property_graph_ddl())

That prints the actual CREATE PROPERTY GRAPH DDL — 4 node tables + 4 edge tables, ~80 lines, fits one screen. Talk track: "Four node types — events, business entities, decisions, candidates — wired into a property graph that BigQuery's GQL engine can traverse natively."

If you'd rather show it visually, BigQuery Studio's Schema view does render property graphs after the DDL has been applied. Run the DDL once before the demo (offline setup), then in the demo just navigate to the graph. Don't gm-compile in real time — that's bigquery_ontology plumbing not relevant to this story.

Phase 2 (30s) — agent execution + extraction

The plan says "execute a simulated ADCP brief in the terminal" but doesn't say which agent or where it runs. A concrete script:

# pre-recorded session: sess-nike-summer
# (the agent itself runs in ADK with the BQAA plugin enabled —
# nothing in this SDK starts an agent; we read what the plugin wrote)

# Server-side extraction once the agent is done:
mgr = client.context_graph()
biz_nodes = mgr.extract_biz_nodes(session_ids=["sess-nike-summer"])
decisions, candidates = mgr.extract_decision_points(
    session_ids=["sess-nike-summer"]
)
print(f"Extracted {len(decisions)} decisions, {len(candidates)} candidates")

Talk track stays mostly correct, but the line "the BQAA plugin asynchronously streams the execution telemetry into BigQuery" is doing two jobs at once — pre-record the agent run (don't trigger it live; that adds 30+ seconds of LLM round-trip uncertainty). Show the plugin → BQ ingestion as a background fact, then run extract_decision_points live. The extraction call is the visible "AI.GENERATE materializes decisions into typed nodes" moment.

Phase 3 (90s) — GQL + business questions

The GQL query in the plan works against the schema. But two things the presenter should know:

1. Conversational Analytics ↔ GQL translation does not exist in this SDK. The plan shows CA generating GQL from natural language. That's a stretch — CA is BigQuery's NL-to-SQL surface, and GQL is a separate query language inside EXECUTE GRAPH. Two honest options:
   • Drop the CA framing for Phase 3. Show the GQL directly as "this is the canned audit query the SDK ships." That matches reality.
   • Or: have the CA layer generate SQL that wraps a GQL EXECUTE GRAPH block. That works in current BQ. But that's not "CA traversing the graph" — it's CA generating SQL which contains GQL.
2. Use the SDK's pre-canned templates rather than handwriting the query. They're correct and match the schema:

gql = mgr.get_eu_audit_gql(
    session_id="sess-nike-summer",
    decision_type="audience_selection",  # optional filter
)
result = client.bq_client.query(
    gql,
    job_config=bigquery.QueryJobConfig(query_parameters=[
        bigquery.ScalarQueryParameter("session_id", "STRING", "sess-nike-summer"),
        bigquery.ScalarQueryParameter("decision_type", "STRING", "audience_selection"),
        bigquery.ScalarQueryParameter("result_limit", "INT64", 200),
    ])
).result()
for row in result:
    print(row.candidate_name, row.candidate_status, row.rejection_rationale)

Talk track: "The SDK ships an EU-audit GQL template — three-hop traversal from event span → decision → candidate — so the same query gives you the exact set of candidates and rejection rationale for any session, without writing graph SQL by hand." That's a stronger story than the bare GQL example because it shows the SDK's value-add (pre-canned audit query, parameterized).

Phase 4 (45s) — operations research

Currently the talk track says "aggregate RejectionReason nodes across thousands of sessions." Two issues: (a) there is no RejectionReason node — it's a string property; (b) "aggregate" needs an actual query. Replace with:

-- Run this against the candidate table directly (cheaper than GQL for aggregation):
SELECT
  rejection_rationale,
  decision_type,
  COUNT(*) AS dropped_count,
  AVG(score) AS avg_score
FROM `proj.dataset.extracted_candidate_nodes` cand
JOIN `proj.dataset.extracted_decision_points` dp
  USING (decision_id)
WHERE cand.status = 'DROPPED'
  AND cand.rejection_rationale IS NOT NULL
GROUP BY rejection_rationale, decision_type
ORDER BY dropped_count DESC
LIMIT 20;

Talk track: "At fleet scale, the candidate table is just rows — a single SQL aggregation rolls up rejection rationales across thousands of sessions. If 'floor price exceeded' dominates, that's a yield-ops signal: the agent is ready to buy but our pricing rules are blocking the buy."

Also worth showing here: WorldChangeAlert (context_graph.py near class WorldChangeAlert). The drift detector compares the BizNode state at evaluation time against the current state; that's the "real-world outcomes" feedback loop the talk track gestures at, but it's a real method, not a hand-wave. One screen of output is enough.

Suggested overall edits

1. Phase 1: rename "6-Pillar" to "4-node decision lineage graph" (or grow the schema first). Drop ContextSnapshot / ConstraintApplication from the talk track until they're real schema. Show mgr.get_property_graph_ddl() output as the artifact.

2. Phase 2: pre-record the agent run; show extract_biz_nodes() + extract_decision_points() calls live. Print row counts for visible payoff.

3. Phase 3: drop the CA-generates-GQL framing; show mgr.get_eu_audit_gql() (three-hop traversal) directly. Use parameterized query — looks more production-grade than literal session IDs in the GQL.

4. Phase 4: replace the GQL aggregation with SQL over the candidates + decision_points tables (cheaper, matches reality). Optionally add a 10-second WorldChangeAlert callout.

5. Demo prereqs section (currently missing): one paragraph naming what has to be set up before the demo runs — dataset created, plugin installed in the demo agent, ~2-3 pre-run sessions in the agent_events table, context_graph().materialize_property_graph() already called. Without this, the demo collapses if anything fails to render.

6. Timing: Phase 1's 45s is right. Phase 2's 30s is too short if you actually trigger an agent — keep it 30s only with a pre-recorded session. Phase 3's 90s is realistic for one query + result narration. Phase 4's 45s is right for one SQL block; 60s if you add WorldChangeAlert.

The narrative arc — black-box → typed graph → traverse for "why" → aggregate for "where to improve" — is solid. The fixes above keep the narrative and pin every claim to a real method or query that already ships in context_graph.py.

[caohy1988]

Three concrete API corrections to my prior comment, plus a reframing on the "6-Pillar" point. All four verified against current main (6656200).

1. Phase 1 command — wrong method name

I wrote mgr.get_property_graph_ddl(). That exists (context_graph.py:1323) but emits the base property graph: TechNode + BizNode + Caused + Evaluated only. No decision tables.

The decision-lineage demo needs mgr.get_decision_property_graph_ddl() (context_graph.py:2256), which adds DecisionPoint, CandidateNode, MadeDecision, and CandidateEdge. Use that for Phase 1's "show the schema" moment.

2. Prereq method — materialize_property_graph() does not exist

I made up that method name. The real options on ContextGraphManager are:

• mgr.create_property_graph(include_decisions=True) (context_graph.py:1345) — emits and runs the CREATE OR REPLACE PROPERTY GRAPH DDL. The include_decisions=True flag is what makes it the decision-lineage graph (matching the DDL get_decision_property_graph_ddl() returns).
• mgr.build_context_graph(session_ids=[...], include_decisions=True) (context_graph.py:2492) — convenience wrapper that runs the extractors AND creates/refreshes the graph in one call.

For the demo prereqs, build_context_graph is the simplest one-shot setup: extracts biz nodes + decision points + candidates from the recorded sessions, materializes the property graph with all decision tables, ready for Phase 3's GQL.

3. Phase 4 SQL — table names off

I wrote extracted_candidate_nodes JOIN extracted_decision_points. The defaults in ContextGraphConfig are:

• decision_points_table: "decision_points" ← no prefix
• candidates_table: "candidates" ← no prefix
• biz_nodes_table: "extracted_biz_nodes" ← this one does have the extracted_ prefix; that's where my muscle-memory came from
• made_decision_edges_table: "made_decision_edges"
• candidate_edges_table: "candidate_edges"

The Phase 4 SQL should be:

SELECT
  rejection_rationale,
  decision_type,
  COUNT(*) AS dropped_count,
  AVG(score) AS avg_score
FROM `proj.dataset.candidates` cand
JOIN `proj.dataset.decision_points` dp
  USING (decision_id)
WHERE cand.status = 'DROPPED'
  AND cand.rejection_rationale IS NOT NULL
GROUP BY rejection_rationale, decision_type
ORDER BY dropped_count DESC
LIMIT 20;

Demos that override ContextGraphConfig need to substitute their own names; the defaults are what a fresh Client.context_graph() produces.

4. "6-Pillar" — the term is real, the count just doesn't add to 6

I called this an overstatement. It's not — docs/context_graph_v3_design.md:17 explicitly defines:

6-Pillar Property Graph — TechNode + BizNode + DecisionPoint + CandidateNode + Caused edges + Evaluated cross-links + MadeDecision edges + CandidateEdge edges

The doc enumerates eight things under the "6-pillar" name. That's an internal inconsistency in the design doc, but "6-Pillar" itself is the project's marketing term. So the demo plan didn't invent it.

The correction is reframing rather than rejection:

Phase 1 should explicitly define what "6-Pillar" means in the demo's voice, since the design doc itself enumerates eight pillars under the same label. Two clean fixes: (a) rename to "6-pillar architecture: 4 node types + 4 edge types reduced to 6 conceptual pillars" with the grouping spelled out, or (b) drop "6-Pillar" from the demo and call it "the decision-lineage property graph: 4 nodes, 4 edges." (b) is shorter and avoids the internal-doc inconsistency entirely.

The substantive blocker remains the same as my prior comment: ContextSnapshot, ConstraintApplication, and a separate RejectionReason node don't exist in the schema. rejection_rationale is a STRING property on CandidateNode. The talk track in Phase 1 needs to drop those three names or the schema needs to grow them — and that's a real PR, not a one-line edit.

Updated Phase 1 talk track (concrete, post-corrections)

mgr = client.context_graph()
print(mgr.get_decision_property_graph_ddl())

"BigQuery's property graph engine sees four node types — events, business entities, decisions, candidates — and four edge types wiring them up. A CandidateNode carries the score, the SELECTED/DROPPED status, and the rejection rationale right on the row. A three-hop GQL traversal (event span → decision → candidate) gives you the full audit trail for any session — no joins, no JSON-digging."

That's accurate to what ships today and still tells the decision-lineage story. The "ContextSnapshot / ConstraintApplication" framing is for a future PR that adds those node tables.

Updated demo prereqs

One paragraph to add to the plan:

Setup (run once, offline): Create the dataset. Run a demo agent (ADK with the BQAA plugin) for 2-3 sessions to populate agent_events. Run client.context_graph().build_context_graph(session_ids=[...], include_decisions=True) once — this calls extract_biz_nodes + extract_decision_points + create_property_graph(include_decisions=True) in sequence, so the demo's Phase 3 GQL has rows to traverse. After that, the demo is read-only.

[caohy1988]

Verified: build_context_graph(session_ids, graph_name=None, use_ai_generate=True, include_decisions=False) per context_graph.py:2492-2497. use_ai_generate=True is the default, but you're right that for a demo the explicit kwarg makes the AI.GENERATE call visible to a viewer reading the snippet — adopting it.

You also caught a real consistency gap I introduced: my prior comment said "all extraction offline, after that the demo is read-only" but Phase 2's earlier text still said "show extract_biz_nodes() + extract_decision_points() live." Those don't compose. Pick one path:

Option A — Safer demo (recommended for 3-4 min slot)

Move all extraction offline into prereqs. Phase 2 becomes a 30s "show what we already have" segment:

# Phase 2 in the demo (read-only):
mgr = client.context_graph()

# Show that the offline build produced typed rows in BigQuery:
print(client.bq_client.query(
    f"SELECT COUNT(*) AS biz_nodes "
    f"FROM `{PROJ}.{DS}.extracted_biz_nodes`"
).result().to_dataframe().iloc[0, 0])

print(client.bq_client.query(
    f"SELECT decision_type, COUNT(*) AS n "
    f"FROM `{PROJ}.{DS}.decision_points` "
    f"GROUP BY decision_type"
).result().to_dataframe())

Talk track stays: "The BQAA plugin streamed the agent's execution into BigQuery while the campaign ran. Offline, an AI.GENERATE extraction pass materialized the unstructured reasoning into typed BizNode and DecisionPoint rows. Here's the row counts and the decision-type breakdown — already in BQ, ready for the next step."

Predictable timing, no live LLM round-trip, no risk of mid-demo AI.GENERATE latency or quota issues. The "AI.GENERATE materialized this" claim is still accurate; you're just showing the result rather than re-running the call.

Option B — More dynamic demo

Keep Phase 2 live, but explicitly call out the cost and the mutation:

# Phase 2 in the demo (LIVE — refreshes graph tables):
results = client.context_graph().build_context_graph(
    session_ids=["sess-nike-summer"],
    use_ai_generate=True,
    include_decisions=True,
)
print(f"Extracted {results['biz_nodes_count']} business entities, "
      f"{results['decision_points_count']} decision points")

Talk track adds: "This live build_context_graph call runs AI.GENERATE server-side — typically 8–20s on a single session — and refreshes the decision_points/candidates/extracted_biz_nodes tables. We'd run it on a schedule in production; here we're showing it live so you can see the typed-extraction step happen."

The framing is honest about what's mutating. The risk is that 8-20s is a real chunk of a 30s phase, leaving little room for narration, plus AI.GENERATE quota / network can blow up the timing in unfriendly ways.

My recommendation

Option A. The demo's value isn't "watch AI.GENERATE run for 15 seconds" — it's "decision lineage is queryable as a typed graph." The typed extraction claim is just as compelling shown as a row-count payoff after offline setup, and the saved 15 seconds buys back narration time for Phase 3 (which is where the GQL traversal and the actual "why did the agent reject this candidate*" story lives).

Updated prereqs paragraph (incorporates your use_ai_generate=True clarity tweak + Option A consistency):

Setup (run once, offline before the demo). Create the dataset. Run a demo agent (ADK with the BQAA plugin enabled) on 2-3 representative sessions to populate agent_events. Then run the one-shot graph builder:

client.context_graph().build_context_graph(
    session_ids=[...],  # the recorded session IDs
    use_ai_generate=True,
    include_decisions=True,
)

This calls extract_biz_nodes + create_cross_links + extract_decision_points + create_property_graph(include_decisions=True) in sequence, producing the extracted_biz_nodes, decision_points, candidates, and edge tables, and materializing the property graph that Phase 3's GQL traverses. After this completes, the demo is read-only — no live AI.GENERATE on the critical path, no graph table mutation during recording.

Beyond Phase 2 / prereq consistency and the use_ai_generate=True clarity, no new blockers. The central drop-or-grow ask on ContextSnapshot / ConstraintApplication / standalone RejectionReason from Phase 1's talk track stands.

[haiyuan-eng-google]

Here is the step-by-step breakdown of the flow Bei proposed:

1. Market Context & The Business Problem

Instead of starting with the Context Graph, start with the "Why."

• The Hook: Focus on the regulatory landscape (EU AI Act, GDPR).
• The Threat: Highlight the massive financial risks, such as fines up to 7% of worldwide annual turnover for non-compliance.
• The Narrative Shift: Frame the evolution of AI from "Systems of Action" (agents doing tasks) to a mandatory need for "Systems of Governance" (tracking and auditing those tasks).

2. Business Value Proposition

Define what the solution actually does for a business leader.

• Focus on trust and transparency.
• Explain the capability of "Decision Lineage"—the ability to prove why an AI made a specific choice at a specific time.

3. Real-World Customer Case (e.g., Yahoo)

Ground the theory in a concrete example to build credibility.

• Why they care: What was the specific regulatory or operational pain point for the customer?
• How it helped: Describe the impact the solution had on their workflow.
• The Proof: Include a customer quote here to transition from "our ideas" to "their success."

4. High-Level Concepts & Demo

Show the product in action, but keep it focused on the "System of Governance" narrative.

• The Demo: Use a screencast recording rather than a live demo to ensure a tight storyline.
• Key Focus: Show the audit trail and decision traces.
• Auditor Persona: Demonstrate how a user (or auditor) can ask the Conversational Agent (CA) questions like, "Did any of these 162 decisions involve demographic bias?" and get an immediate, evidenced answer.

5. Architectural Details (The "How")

Only after the audience understands the value and sees the proof should you dive into the technicalities.

• Introduce the ADK media planning agent.
• Explain the BigQuery graph integration.
• Discuss the temporal aspect: how actions and decisions are linked by timestamps to show patterns over time.

---

Summary of the Flow

Market Pain → Business Solution → Customer Proof → Practical Demo → Technical Architecture

This structure ensures that if the meeting runs short or leadership asks questions early, you have already landed the most important "Value" and "Risk" points.