Dual-Graph System of Action: Autonomous Refund Agent Lab Guide¶
Overview¶
In this hands-on lab, you explore and verify a Dual-Graph System of Action on Google Cloud using Google Agent Development Kit 2.0 (ADK 2.0), Cloud Spanner Graph, BigQuery Graph, Cloud Spanner Data Boost, and Knowledge Catalog.
Autonomous refund workflows require two operational guarantees before and after modifying data:
- Pre-action context: The agent must verify customer history and tiered policy rules against operational databases before modifying an order.
- Post-action lineage: The system must record every evaluation step, policy rule, and database mutation in an append-only audit log.
What you'll learn¶
- How to inspect OperationalContextGraph schemas and Knowledge Catalog metric
contracts (
soa-business-glossary,refund-metric-contract) in the Google Cloud Console - How ADK 2.0 (
gemini-3-flash-previewand ISO GQL) pauses for customer confirmation before committing an eligible Standard refund (Activity 1: Customer A) - How Cloud Spanner Graph blocks database writes when a customer exceeds the 100-day return limit (Activity 2: Customer B)
- How Knowledge Catalog applies tier-aware contracts to approve eligible VIP refunds (Activity 3: Customer C)
- How to run cross-engine federated queries joining BigQuery ActionLineageGraph and Cloud Spanner OperationalContextGraph over Cloud Spanner Data Boost (Activity 4)
Setup and requirements¶
How the Dual-Graph System of Action works behind the UI¶
Dual-Graph architecture and 5-step ADK 2.0 workflow¶
The diagram below illustrates how UI 1 (/shop) and UI 2 (/console)
interact with the 5-step ADK 2.0 workflow, Knowledge Catalog,
Cloud Spanner OperationalContextGraph, and BigQuery
ActionLineageGraph:
Task 1. Open the lab web interfaces and Google Cloud Console¶
- Locate
shopping_mall_url() and data_engineer_console_url() in your Qwiklabs environment panel and open both URLs in separate browser tabs. - Open the Google Cloud Console (
https://console.cloud.google.com) in a third browser tab using your Qwiklabs student credentials and verify that your lab project () is selected.
Task 2. Inspect the underlying databases in the Google Cloud Console¶
Before triggering any agent actions in the web UI, inspect the underlying databases and catalog resources directly in the Google Cloud Console to see how the graph schemas, relational tables, and governance contracts are stored.
Property graph node and edge schemas¶
Both graphs share a durable cross-graph reconciliation identifier
(order_items.refund_trace_id in Cloud Spanner and agent_sessions.trace_id in
BigQuery):
2a. Inspect governed business terms in Knowledge Catalog¶
The System of Action Business Glossary (soa-business-glossary) governs
three top-level refund policy metric terms:
Customer Loyalty Tier(customer-loyalty-tier): Defines the tier routing contract (STANDARDvs.VIP).Order Age in Days(order-age-days): Defines the 30-day post-delivery eligibility window (status = 'Complete'andage <= 30).-
Rolling 100-Day Refund Count(rolling-100d-refund-count): Defines how Step 3 counts returnedorder_items(status = 'Returned') over the trailing 100 days excluding the target order. -
In the Google Cloud Console search bar, search for Knowledge Catalog and open the service, then select Glossaries in the left navigation menu.
- Click System of Action Business Glossary (
soa-business-glossaryin locationGlobal). - Click each of the three governed business glossary terms (Customer Loyalty Tier, Order Age in Days, and Rolling 100-Day Refund Count) listed directly under the glossary to inspect their definitions.
- In the left navigation menu of Knowledge Catalog, click Metadata
Types to inspect the custom
Refund Metric Contract(refund-metric-contract) aspect type. Observe the 5 governed record fields (returned_statusfor Returned Order Item Status,eligible_order_statusfor Eligible Delivered Order Status,rolling_window_daysfor Rolling Refund Window Days,standard_tierfor Standard Customer Tier Code, andvip_tierfor VIP Customer Tier Code) that define canonical status codes and time windows across the system.
resolve_catalog_contract), the agent queries these
Knowledge Catalog entries via the Catalog API so canonical parameters
(returned_status = 'Returned', eligible_order_status =
'Complete', rolling_window_days = 100) are never hardcoded
in LLM prompts. Meanwhile, the tier-specific operational thresholds
(max_refunds_100d = 10 for STANDARD vs. 20 for VIP,
and return_window_days = 30) are enforced by the
policy_conditions nodes in Cloud Spanner's
OperationalContextGraph (inspected in Task 2b).
2b. Query OperationalContextGraph in Cloud Spanner Studio¶
The thelook-soa-db database in Cloud Spanner combines 6 Relational-to-Graph
(R2G) operational tables (users, orders, order_items, inventory_items,
products, distribution_centers) and 3 Unstructured-to-Graph (U2G) policy
tables (policies, policy_conditions, policy_restrictions) into a single
ISO GQL property graph named OperationalContextGraph.
- In the Google Cloud Console navigation menu, go to Spanner > Instances.
- Click System of Action Graph Instance (
soa-graph-instance), then click the databasethelook-soa-db. - In the left navigation menu of
thelook-soa-db, click Spanner Studio and expandTablesandGraphsin the Explorer sidebar. - Click the three-dots (View actions) menu next to
OperationalContextGraphand selectView/modify visuallyto inspect the visualized graph schema mapping the 8 node tables and 7 edge tables (places,contains_item,is_product,supplied_by,governed_by,requires_condition,enforces_restriction). -
In Spanner Studio, open a new SQL/GQL editor tab and run the following native ISO GQL query to visualize the live property graph data in the Google Cloud Console:
-- Purpose: Visualize the live R2G + U2G property graph topology in Spanner Studio. -- Target Engine: Cloud Spanner (thelook-soa-db -> OperationalContextGraph). -- How It Works: Traverses from users -> orders -> inventory_items -> products -- -> distribution_centers and links products to active policies, tier-matched -- policy_conditions, and policy_restrictions, returning JSON graph elements. -- Information Gathered: Full node/edge JSON objects to render the interactive -- property graph in Cloud Spanner Studio (Graph and Table views). GRAPH OperationalContextGraph MATCH (u:users)-[e_places:places]->(o:orders {order_id: 90124}) -[e_item:contains_item]->(ii:inventory_items) -[e_prod:is_product]->(p:products) -[e_dc:supplied_by]->(dc:distribution_centers), (p)-[e_gov:governed_by]->(pol:policies {status: 'ACTIVE'}) -[e_cond:requires_condition]->(cond:policy_conditions), (pol)-[e_res:enforces_restriction]->(res:policy_restrictions) WHERE cond.applicable_tier = u.customer_tier RETURN TO_JSON(u) AS user_node, TO_JSON(e_places) AS places_edge, TO_JSON(o) AS order_node, TO_JSON(e_item) AS contains_item_edge, TO_JSON(ii) AS inventory_node, TO_JSON(p) AS product_node, TO_JSON(dc) AS dc_node, TO_JSON(pol) AS policy_node, TO_JSON(cond) AS condition_node, TO_JSON(res) AS restriction_node; -
In the Spanner Studio results pane, toggle between the Graph view (where you can click and drag the Cloud Spanner nodes and edges) and the Table view. Notice that
o.statusis currently'Complete'ande_item.refund_trace_idisNULL.
2c. Inspect ActionLineageGraph in BigQuery Studio¶
- In the Google Cloud Console navigation menu, go to BigQuery > Studio.
- In the Explorer pane, expand your project and expand the dataset
soa_action_lineage. - Observe the four lineage tables (
agent_sessions,workflow_nodes,policy_evaluations,agent_actions) under Tables, the property graphActionLineageGraphunder the Graphs menu item, and the external connection.spanner-data-boost under Connections. - Click Graphs >
ActionLineageGraphto inspect the visualized graph schema (agent_sessions→workflow_nodes→policy_evaluations→agent_actions) and node/edge property definitions in the Google Cloud Console.
Task 3. Activity 1: Customer A eligible refund and 2-turn confirmation¶
In this activity, you use UI 1 (/shop) as Customer A (Alice Chen,
user_id: 1001, STANDARD tier) to test contextual order inference and the
two-turn confirmation gate, then verify the database changes in Cloud Spanner
Studio, BigQuery Studio, and UI 2 (/console).
Two-turn confirmation sequence (PENDING_CONFIRMATION → APPROVED)¶
When the agent resolves a valid customer order, it pauses so the customer can confirm the order number, product photo, item name, and price before committing the transaction:
3a. Trigger Turn 1 (PENDING_CONFIRMATION) in UI 1¶
Alice Chen (user_id: 1001, STANDARD tier) has three active orders in the
storefront:
ORD-90124: Alpine Gore-Tex Waterproof Shell Jacket ($129.00), statusComplete, delivered 14 days ago (2prior returns in 100 days).ORD-90125: Polarized Aviator Titanium Sunglasses ($165.00), statusComplete, delivered 45 days ago.-
ORD-90126: Cashmere Ribbed Winter Beanie ($58.00), statusShipped(in transit). -
In UI 1 (
/shop), ensure Alice Chen (user_id: 1001,STANDARDtier) is selected in the Active Customer Persona Switcher. -
In the ADK 2.0 Refund Agent chat widget on the right, either click the Request refund for ORD-90124 (Eligible Standard) prompt chip or type a natural-language request without an order number:
-
Observe the live
[1/5]..[5/5]step telemetry stream in the chat widget and verify that the agent pauses atPENDING_CONFIRMATIONwith aConfirm Refund: ORD-90124 — Alpine Gore-Tex Waterproof Shell Jacket ($129.00)button.
During Turn 1, the workflow runs through these steps:
- Step 1 (
IntentAgent): Queries Alice's active orders in Cloud Spanner and resolvesorder_id = 90124(either from the prompt chip or by inferring it from questions like"Can I refund my last order?"usinggemini-3-flash-preview). - Step 2 (
resolve_catalog_contract): Fetches the parameter definitions forrolling-100d-refund-countfrom Knowledge Catalog. - Step 3 (
evaluate_spanner_policy): Runs the ISO GQL query onOperationalContextGraph, matchingCOND-REFUND-STD-100D-30Dand confirmingprior_refund_count_100d = 2 < 10andtarget_order_age_days = 14 <= 30(evaluation_result = 'PASS'). - Step 4 (
route_and_commit_action): Waits for customer confirmation before updating Cloud Spanner, records aPENDING_CONFIRMATIONtrace (action_type = 'AWAIT_CUSTOMER_CONFIRMATION') in BigQuery, and formats the confirmation prompt via Step 5 (ResponseAgent).
3b. Verify in Cloud Spanner Studio that the order is not yet mutated¶
-
Switch to your Cloud Spanner Studio browser tab (
thelook-soa-db) and run:-- Purpose: Verify the live transactional state of Order 90124 before and after -- customer confirmation (Turn 1 PENDING_CONFIRMATION vs. Turn 2 APPROVED). -- Target Engine: Cloud Spanner (thelook-soa-db relational tables: orders, order_items). -- How It Works: Joins orders and order_items on (user_id, order_id) for order_id = 90124. -- Information Gathered: Current order_status ('Complete' before confirmation, -- 'Returned' after commit), returned_at timestamp, item_status, and the -- cross-graph reconciliation key (refund_trace_id). SELECT o.order_id, o.status AS order_status, o.returned_at, oi.status AS item_status, oi.refund_trace_id FROM orders AS o JOIN order_items AS oi ON o.user_id = oi.user_id AND o.order_id = oi.order_id WHERE o.order_id = 90124; -
Verify that
order_statusis still'Complete'andrefund_trace_idisNULL:order_id | order_status | returned_at | item_status | refund_trace_id ---------+--------------+-------------+-------------+---------------- 90124 | Complete | NULL | Complete | NULL
PENDING_CONFIRMATION) checks eligibility against
OperationalContextGraph and records an audit trace in BigQuery
without updating any row in Cloud Spanner.
3c. Confirm the refund (Turn 2 APPROVED) and verify the mutation¶
- Return to UI 1 (
/shop) and clickConfirm Refund: ORD-90124 — Alpine Gore-Tex Waterproof Shell Jacket ($129.00)(or typeYes, please proceed). - In Turn 2, the agent re-checks the policy in
OperationalContextGraph, updatesORD-90124toReturnedin Cloud Spanner, writes the newtrace_idtoorder_items.refund_trace_id, and displays theAPPROVEDbadge. -
Switch back to Cloud Spanner Studio and re-run the same SQL query from Step 3b. Confirm that
order_statusanditem_statusare now'Returned',returned_atis populated with the commit timestamp, andrefund_trace_idcontains the exact UUIDtrace_iddisplayed in the chat widget:order_id | order_status | returned_at | item_status | refund_trace_id ---------+--------------+-----------------------------+-------------+------------------------------------------- 90124 | Returned | 2026-10-29T05:12:41.102345Z | Returned | trace-a1b2c3d4-5678-4901-b234-567890abcdef
3d. Inspect the context and lineage graphs in UI 2 and BigQuery Studio¶
- In UI 1 (
/shop), click Inspect in Data Engineer Console on theAPPROVEDchat card to open UI 2 (/console) pre-filtered to Customer A'strace_id. - In UI 2 (
/console), click the nodes in the Interactive Dual-Graph Visualizer (User 1001,Order 90124,Product,Policy POL-REFUND-STD-V1,Condition COND-REFUND-STD-100D-30D, and the orange BigQuery lineage nodes) to inspect their live properties in the Node Property Inspector. -
In Tab 1 (1. Cloud Spanner Context Graph), click Run Query (or run the same query directly in Cloud Spanner Studio):
-- Purpose: Evaluate Customer A's operational context and tiered refund policy -- eligibility in a single two-stage ISO GQL traversal. -- Target Engine: Cloud Spanner (thelook-soa-db -> OperationalContextGraph). -- How It Works: -- Stage 1 (MATCH): Traverses R2G (users -> orders -> inventory_items -> -- products -> distribution_centers) and U2G (products -> policies -> -- policy_conditions / policy_restrictions) filtered by customer_tier. -- Stage 2 (NEXT + OPTIONAL MATCH): Counts distinct returned items across -- other orders within the 100-day rolling window. -- Information Gathered: Customer tier, target order status/age/price, product -- and fulfillment center names, active policy/condition IDs, 100-day return -- cap (max_refunds_100d), 30-day window, and observed prior_refund_count_100d. GRAPH OperationalContextGraph MATCH (u:users {id: 1001}) -[:places]->(target_o:orders {order_id: 90124}) -[target_oi:contains_item]->(ii:inventory_items)-[:is_product]->(p:products) -[:supplied_by]->(dc:distribution_centers), (p)-[:governed_by]->(pol:policies {status: 'ACTIVE'}) -[:requires_condition]->(cond:policy_conditions), (pol)-[:enforces_restriction]->(res:policy_restrictions) WHERE u.customer_tier IN ('STANDARD', 'VIP') AND cond.applicable_tier = u.customer_tier RETURN u.id AS user_id, u.email AS email, u.customer_tier AS customer_tier, target_o.order_id AS target_order_id, target_o.status AS target_order_status, TIMESTAMP_DIFF(CURRENT_TIMESTAMP(), target_o.delivered_at, DAY) AS target_order_age_days, ROUND(SUM(target_oi.sale_price), 2) AS target_order_price, STRING_AGG(DISTINCT p.name, ', ') AS product_names, STRING_AGG(DISTINCT dc.name, ', ') AS distribution_center_names, pol.policy_id AS policy_id, pol.name AS policy_name, cond.condition_id AS condition_id, cond.max_refunds_100d AS max_refunds_100d, cond.return_window_days AS return_window_days, res.action_code AS restriction_action GROUP BY user_id, email, customer_tier, target_order_id, target_order_status, target_order_age_days, policy_id, policy_name, condition_id, max_refunds_100d, return_window_days, restriction_action NEXT -- Stage 2: Count prior returned items in the rolling 100-day window OPTIONAL MATCH (u2:users)-[:places]->(hist_o:orders)-[hist_oi:contains_item]->(:inventory_items) WHERE u2.id = user_id AND hist_o.order_id != target_order_id AND hist_oi.status = 'Returned' AND COALESCE(hist_oi.returned_at, hist_o.returned_at, hist_o.created_at) >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 100 DAY) RETURN user_id, email, customer_tier, target_order_id, target_order_status, product_names, distribution_center_names, target_order_price, target_order_age_days, COUNT(DISTINCT hist_oi.id) AS prior_refund_count_100d, policy_id, policy_name, condition_id, max_refunds_100d, return_window_days, restriction_action GROUP BY user_id, email, customer_tier, target_order_id, target_order_status, product_names, distribution_center_names, target_order_price, target_order_age_days, policy_id, policy_name, condition_id, max_refunds_100d, return_window_days, restriction_action; -
Switch to Tab 2 (2. BigQuery Action Lineage Graph) in UI 2 (
/console) and click Run Query, or open BigQuery Studio and run the following query to inspect both thePENDING_CONFIRMATION(Turn 1) andAPPROVED(Turn 2) lineage traces recorded fortarget_order_id = 90124:-- Purpose: Audit the append-only agent decision lineage for Customer A's -- Order 90124 across Turn 1 (PENDING_CONFIRMATION) and Turn 2 (APPROVED). -- Target Engine: BigQuery (soa_action_lineage dataset backing ActionLineageGraph). -- How It Works: Joins agent_sessions -> workflow_nodes -> policy_evaluations -- -> agent_actions along the ActionLineageGraph primary/foreign keys. -- Information Gathered: Session trace_id, Knowledge Catalog term (catalog_term_id), -- evaluated policy name, observed vs. maximum 100-day refunds, PASS/FAIL -- result, executed action_type, decision_status, and commit timestamp. SELECT s.trace_id, s.customer_id, s.target_order_id, n.node_name, pe.catalog_term_id, pe.policy_name, pe.observed_refunds_100d AS prior_refund_count_100d, pe.max_refunds_100d, pe.evaluation_result, act.action_type, act.decision_status, act.created_at AS committed_at FROM `soa_action_lineage.agent_sessions` AS s JOIN `soa_action_lineage.workflow_nodes` AS n ON s.trace_id = n.trace_id AND n.node_name = 'evaluate_spanner_policy' JOIN `soa_action_lineage.policy_evaluations` AS pe ON n.node_exec_id = pe.node_exec_id JOIN `soa_action_lineage.agent_actions` AS act ON pe.eval_id = act.eval_id WHERE s.customer_id = 1001 AND s.target_order_id = 90124 ORDER BY s.started_at DESC;
FROM GRAPH_TABLE(soa_action_lineage.ActionLineageGraph MATCH ...)
query shown in Tab 2 of UI 2 (/console). On
standard on-demand billing (gcpfree), UI 2 automatically falls
back to the equivalent parameterized SQL JOIN above.
Task 4. Activity 2: Customer B policy denial (STANDARD tier)¶
In this activity, you test how the deterministic graph policy gate blocks an
autonomous refund when Customer B (Jordan Taylor, user_id: 2048,
STANDARD tier) reaches or exceeds the 100-day return threshold (12 >= 10),
then verify the blocked mutation and rejection lineage in Cloud Spanner
Studio, BigQuery Studio, and UI 2 (/console).
4a. Trigger Turn 1 (PENDING_CONFIRMATION) and Turn 2 (DENIED) in UI 1¶
- Return to UI 1 (
/shop) and select Jordan Taylor (user_id: 2048,STANDARDtier) in the Active Customer Persona Switcher. - Review Jordan Taylor's order and return profile in the main panel (
100-Day Returned Items:12 / 10forORD-81001throughORD-81012returned within the trailing 100-day window;ORD-90588: CloudStride Trail Running Shoes for$148.00, statusComplete, delivered 10 days ago). -
In the ADK 2.0 Refund Agent chat widget on the right, either click the Request refund for ORD-90588 (Standard 12 >= 10 Limit) prompt chip or type:
-
Observe Turn 1 (
PENDING_CONFIRMATION), then clickConfirm Refund: ORD-90588 — CloudStride Trail Running Shoes ($148.00)to execute Turn 2 (DENIED).
During these two turns, the workflow executes the following steps:
- Step 1 (
IntentAgent): Resolvesorder_id = 90588(CloudStride Trail Running Shoes,$148.00) foruser_id = 2048. - Step 2 (
resolve_catalog_contract): Fetches parameter definitions forrolling-100d-refund-countfrom Knowledge Catalog. - Step 3 (
evaluate_spanner_policy): TraversesOperationalContextGraphin Cloud Spanner (u.customer_tier = 'STANDARD', matchingCOND-REFUND-STD-100D-30Dwithmax_refunds_100d = 10) and countsprior_refund_count_100d = 12in theNEXTstage. Because12 >= 10, Step 3 returnsevaluation_result = 'FAIL'andfailure_code = 'MAX_REFUNDS_EXCEEDED'. - Step 4 (
route_and_commit_action): On Turn 1, the workflow pauses atPENDING_CONFIRMATION(action_type = 'AWAIT_CUSTOMER_CONFIRMATION') for customer verification. On Turn 2, the policy check blocks the refund (decision_status = 'DENIED',action_type = 'BLOCK_SPANNER_MUTATION') without updatingORD-90588in Cloud Spanner.
4b. Verify in Cloud Spanner Studio that the denied order was not mutated¶
-
Switch to your Cloud Spanner Studio browser tab (
thelook-soa-db) and run:-- Purpose: Verify that Order 90588 remains untouched in Cloud Spanner after -- Turn 2 policy denial (BLOCK_SPANNER_MUTATION). -- Target Engine: Cloud Spanner (thelook-soa-db relational tables: orders, order_items). -- How It Works: Joins orders and order_items on (user_id, order_id) for order_id = 90588. -- Information Gathered: Confirms order_status and item_status remain 'Complete', -- returned_at is NULL, and refund_trace_id is NULL. SELECT o.order_id, o.status AS order_status, o.returned_at, oi.status AS item_status, oi.refund_trace_id FROM orders AS o JOIN order_items AS oi ON o.user_id = oi.user_id AND o.order_id = oi.order_id WHERE o.order_id = 90588; -
Confirm that
order_statusanditem_statusremain'Complete',returned_atisNULL, andrefund_trace_idisNULL. TheBLOCK_SPANNER_MUTATIONaction blocked the database write:order_id | order_status | returned_at | item_status | refund_trace_id ---------+--------------+-------------+-------------+---------------- 90588 | Complete | NULL | Complete | NULL
OperationalContextGraph
(prior_refund_count_100d = 12 >= max_refunds_100d = 10), the
workflow blocks the database update in Step 4 based on the graph query result.
4c. Inspect the policy denial in UI 2 and Cloud Spanner Studio¶
- In UI 1 (
/shop), click Inspect in Data Engineer Console on theDENIEDchat card to open UI 2 (/console) pre-filtered to Customer B'sDENIEDtrace_id. - In UI 2 (
/console), click the nodes in the Interactive Dual-Graph Visualizer (User 2048,Order 90588,Product,Policy POL-REFUND-STD-V1,Condition COND-REFUND-STD-100D-30D,PolicyRestriction (DENY_AUTONOMOUS_REFUND)withrestriction_id: RES-DENY-AUTO-REFUND, and the BigQueryFAIL/DENIEDlineage nodes) to inspect their live properties in the Node Property Inspector. - Scroll to the bottom of UI 2 (
/console) and click Preview Glossary & Contract (in Knowledge Catalog Semantic Contract) and Preview return_policy_v1.md (in Policy Document (U2G) & Extracted Triples) to inspect the governedrolling-100d-refund-countcontract and source policy rules. - In Tab 1 (1. Cloud Spanner Context Graph), click the
Activity 2: Customer B (2048 / ORD-90588 Denied)preset button to load the same two-stage ISO GQL query from Task 3d filtered foru:users {id: 2048}andtarget_o:orders {order_id: 90588}, then click Run Query (or run the generated query in Cloud Spanner Studio). - Verify from the query results that although
target_order_status = 'Complete'andtarget_order_age_days = 10(within the 30-day window), Customer B hascustomer_tier = 'STANDARD',condition_id = 'COND-REFUND-STD-100D-30D',prior_refund_count_100d = 12, andmax_refunds_100d = 10, triggeringrestriction_action = 'DENY_AUTONOMOUS_REFUND'.
4d. Inspect the rejection lineage in UI 2 and BigQuery Studio¶
- Switch to Tab 2 (2. BigQuery Action Lineage Graph) in UI 2
(
/console), click theActivity 2: ActionLineageGraph GQL (Denial)preset button (orStandard SQL JOIN Equivalent (On-Demand Fallback)), and click Run Query. - Optionally, re-run the BigQuery SQL query from Task 3d in BigQuery
Studio with
WHERE s.customer_id = 2048 AND s.target_order_id = 90588(also addingact.rejection_reasonto theSELECTlist) to inspect both the Turn 1 (PENDING_CONFIRMATION) and Turn 2 (DENIED) audit rows. - Verify that
ActionLineageGraphrecordscatalog_term_id = 'rolling-100d-refund-count',prior_refund_count_100d = 12,max_refunds_100d = 10,evaluation_result = 'FAIL',action_type = 'BLOCK_SPANNER_MUTATION', anddecision_status = 'DENIED'alongside therejection_reason.
Task 5. Activity 3: Customer C VIP approval via Knowledge Catalog (VIP)¶
In this activity, you verify how contextual graph routing and Knowledge
Catalog resolve a higher policy threshold (max_refunds_100d = 20)
for Customer C (Claire Vance, user_id: 3072, VIP tier), approving a
refund even though Customer C has the same 100-day return count (12 returns)
that blocked Customer B in Activity 2.
5a. Trigger Turn 1 (PENDING_CONFIRMATION) and Turn 2 (APPROVED) in UI 1¶
- Return to UI 1 (
/shop) and select Claire Vance (user_id: 3072,VIPtier) in the Active Customer Persona Switcher. - Review Claire Vance's order and return profile in the main panel (
100-Day Returned Items:12 / 20forORD-82001throughORD-82012returned within the trailing 100-day window, governed by theVIPtier limit of20;ORD-90910: Tailored Italian Wool Travel Blazer for$210.00, statusComplete, delivered 7 days ago). -
In the ADK 2.0 Refund Agent chat widget on the right, click the Request refund for ORD-90910 (VIP 12 < 20 Limit) prompt chip or type:
-
Observe Turn 1 (
PENDING_CONFIRMATION), then clickConfirm Refund: ORD-90910 — Tailored Italian Wool Travel Blazer ($210.00)to execute Turn 2 (APPROVED).
During these two turns, the workflow executes the following steps:
- Step 1 (
IntentAgent): Queries Claire Vance's active orders and resolvesorder_id = 90910(Tailored Italian Wool Travel Blazer,$210.00). - Step 2 (
resolve_catalog_contract): Identifiescustomer_tier = 'VIP'foruser_id = 3072and resolves the parameter mapping forcustomer-loyalty-tierfrom Knowledge Catalog. - Step 3 (
evaluate_spanner_policy): Matchesu.customer_tier = 'VIP'againstCOND-REFUND-VIP-100D-30D(max_refunds_100d = 20) inOperationalContextGraph. Because12 < 20and7 <= 30, the policy evaluation passes (evaluation_result = 'PASS'). - Step 4 (
route_and_commit_action): Following customer confirmation in Turn 1, Turn 2 updatesORD-90910toReturnedin Cloud Spanner, writes the newtrace_idtoorder_items.refund_trace_id, and records theAPPROVEDdecision in BigQuery.
5b. Verify the committed VIP refund in Cloud Spanner Studio¶
-
Switch to your Cloud Spanner Studio browser tab (
thelook-soa-db) and run:-- Purpose: Verify the live transactional state of VIP Order 90910 after Turn 2 -- customer confirmation and refund approval (COMMIT_SPANNER_REFUND). -- Target Engine: Cloud Spanner (thelook-soa-db relational tables: orders, order_items). -- How It Works: Joins orders and order_items on (user_id, order_id) for order_id = 90910. -- Information Gathered: Confirms order_status and item_status are 'Returned', -- returned_at is populated, and refund_trace_id matches the APPROVED trace_id. SELECT o.order_id, o.status AS order_status, o.returned_at, oi.status AS item_status, oi.refund_trace_id FROM orders AS o JOIN order_items AS oi ON o.user_id = oi.user_id AND o.order_id = oi.order_id WHERE o.order_id = 90910; -
Confirm that
order_statusanditem_statusare'Returned',returned_atis populated with the commit timestamp, andrefund_trace_idmatches the UUIDtrace_iddisplayed on theAPPROVEDchat card:order_id | order_status | returned_at | item_status | refund_trace_id ---------+--------------+-----------------------------+-------------+------------------------------------------- 90910 | Returned | 2026-10-29T06:22:08.512345Z | Returned | trace-c3d4e5f6-7890-4123-b456-7890abcdef12
12 returned items in the last 100 days. However, Knowledge
Catalog's customer-loyalty-tier contract binds
vip_tier = 'VIP' so Cloud Spanner's
OperationalContextGraph routes Customer C's VIP
profile to COND-REFUND-VIP-100D-30D
(max_refunds_100d = 20), approving the request.
5c. Inspect the VIP policy resolution in UI 2 and Cloud Spanner Studio¶
- In UI 1 (
/shop), click Inspect in Data Engineer Console on theAPPROVEDchat card forORD-90910to open UI 2 (/console) pre-filtered to Customer C'strace_id. - In UI 2 (
/console), click the nodes in the Interactive Dual-Graph Visualizer (User 3072,Order 90910,Product,Policy POL-REFUND-STD-V1,Condition COND-REFUND-VIP-100D-30D, and the BigQueryPASS/APPROVEDlineage nodes) to inspect their live attributes in the Node Property Inspector. - At the bottom of UI 2 (
/console), open Preview Glossary & Contract in the Knowledge Catalog Semantic Contract panel to inspect the resolvedcustomer-loyalty-tiercontract (vip_tier = 'VIP') and its canonical SQL/GQL mapping, and open Preview return_policy_v1.md in the Policy Document (U2G) & Extracted Triples panel to verifyCOND-REFUND-VIP-100D-30D(max_refunds_100d = 20). - In Tab 1 (1. Cloud Spanner Context Graph), click the
Activity 3: Customer C (3072 / ORD-90910 VIP)preset button to load the two-stage ISO GQL query filtered foru:users {id: 3072}andtarget_o:orders {order_id: 90910}, then click Run Query (or run the generated query directly in Cloud Spanner Studio). - Verify from the query results that
customer_tier = 'VIP',condition_id = 'COND-REFUND-VIP-100D-30D',prior_refund_count_100d = 12, andmax_refunds_100d = 20.
5d. Inspect the VIP approval lineage in UI 2 and BigQuery Studio¶
- Switch to Tab 2 (2. BigQuery Action Lineage Graph) in UI 2
(
/console), click theActivity 1 & 3: ActionLineageGraph GQL (Approval)preset button (orStandard SQL JOIN Equivalent (On-Demand Fallback)), and click Run Query. - Optionally, re-run the BigQuery SQL query from Task 3d in BigQuery
Studio with
WHERE s.customer_id = 3072 AND s.target_order_id = 90910to inspect both the Turn 1 (PENDING_CONFIRMATION) and Turn 2 (APPROVED) lineage traces. - Verify that
ActionLineageGraphattributes the approval tocatalog_term_id = 'customer-loyalty-tier'withprior_refund_count_100d = 12,max_refunds_100d = 20,evaluation_result = 'PASS',action_type = 'COMMIT_SPANNER_REFUND', anddecision_status = 'APPROVED'.
Task 6. Activity 4: Cross-engine federated audit with Spanner Data Boost¶
After completing Activities 1, 2, and 3, run a single cross-engine federated
query that joins BigQuery's soa_action_lineage tables with live Cloud Spanner
OperationalContextGraph nodes over Cloud Spanner Data Boost.
EXTERNAL_QUERY over the spanner-data-boost connection
(use_data_boost = true, use_parallelism = true),
partitionable ISO GQL subqueries execute on isolated serverless compute. This
queries live Spanner state without consuming transactional CPU on
soa-graph-instance and without requiring an ETL pipeline.
The federated query pushes three ISO GQL lookups down to Spanner Data Boost
(customer tiers sp_u, order statuses sp_o, and refund_trace_id keys on
contains_item edges sp_oi) and joins them with BigQuery's four
ActionLineageGraph tables:
Run and verify the federated audit query¶
- In UI 2 (
/console), select Tab 3 (3. Federated Spanner Data Boost) and click Run Query. -
To run the same federated query directly inside the Google Cloud Console, switch to BigQuery Studio, replace
YOUR_PROJECT_ID.us-central1.spanner-data-boostwith your lab'sspanner_connection_id(), and run the following SQL query: -- Purpose: Perform a zero-ETL cross-engine audit reconciling BigQuery -- ActionLineageGraph decisions with live Cloud Spanner OperationalContextGraph state. -- Target Engine: BigQuery federated to Cloud Spanner via EXTERNAL_QUERY and -- Cloud Spanner Data Boost (spanner-data-boost). -- How It Works: Joins BigQuery's four lineage tables with three root-partitionable -- ISO GQL subqueries pushed down to isolated Spanner Data Boost compute -- for live users (sp_u), orders (sp_o), and contains_item edges (sp_oi). -- Information Gathered: End-to-end reconciliation proving that APPROVED -- BigQuery traces match live Spanner 'Returned' orders and identical -- refund_trace_id keys, while DENIED traces leave Spanner orders 'Complete'. SELECT s.trace_id, sp_u.email AS live_spanner_email, sp_u.customer_tier AS live_spanner_tier, s.target_order_id, sp_o.live_spanner_order_status, sp_o.live_spanner_returned_at, sp_oi.live_spanner_refund_trace_id, pe.catalog_term_id, pe.observed_refunds_100d AS prior_refund_count_100d, pe.max_refunds_100d, pe.evaluation_result, act.action_type, act.decision_status FROM `soa_action_lineage.agent_sessions` AS s JOIN `soa_action_lineage.workflow_nodes` AS n ON s.trace_id = n.trace_id AND n.node_name = 'evaluate_spanner_policy' JOIN `soa_action_lineage.policy_evaluations` AS pe ON n.node_exec_id = pe.node_exec_id JOIN `soa_action_lineage.agent_actions` AS act ON pe.eval_id = act.eval_id -- Push down ISO GQL user lookup to Spanner Data Boost JOIN EXTERNAL_QUERY( 'YOUR_PROJECT_ID.us-central1.spanner-data-boost', ''' GRAPH OperationalContextGraph MATCH (u:users) WHERE u.id IN (1001, 2048, 3072) RETURN u.id AS user_id, u.email AS email, u.customer_tier AS customer_tier ''' ) AS sp_u ON s.customer_id = sp_u.user_id -- Push down ISO GQL order status lookup to Spanner Data Boost JOIN EXTERNAL_QUERY( 'YOUR_PROJECT_ID.us-central1.spanner-data-boost', ''' GRAPH OperationalContextGraph MATCH (o:orders) WHERE o.user_id IN (1001, 2048, 3072) RETURN o.user_id AS user_id, o.order_id AS order_id, o.status AS live_spanner_order_status, CAST(o.returned_at AS STRING) AS live_spanner_returned_at ''' ) AS sp_o ON s.customer_id = sp_o.user_id AND s.target_order_id = sp_o.order_id -- Push down ISO GQL contains_item edge lookup to verify refund_trace_id JOIN EXTERNAL_QUERY( 'YOUR_PROJECT_ID.us-central1.spanner-data-boost', ''' GRAPH OperationalContextGraph MATCH (:orders)-[oi:contains_item]->(:inventory_items) WHERE oi.user_id IN (1001, 2048, 3072) RETURN oi.order_id AS order_id, oi.refund_trace_id AS live_spanner_refund_trace_id ''' ) AS sp_oi ON s.target_order_id = sp_oi.order_id ORDER BY s.started_at DESC; -
Verify the cross-graph audit results in the query output table.
Confirm these three outcomes in the query output:
- Each
EXTERNAL_QUERYblock runs an ISO GQLGRAPH OperationalContextGraph MATCHquery on isolated Spanner Data Boost compute (use_data_boost = true,use_parallelism = true). - For
ORD-90124(Standard) andORD-90910(VIP),live_spanner_order_statusis'Returned'andlive_spanner_refund_trace_idmatches the BigQueryAPPROVEDtrace_id. - For
ORD-90588(Standard),live_spanner_order_statusremains'Complete',live_spanner_refund_trace_idisNULL, anddecision_statusis'DENIED'.
Task 7. Additional edge-case scenarios in UI 1¶
You can also test additional edge-case and conversational scenarios under
Customer A (Alice Chen, user_id: 1001) in UI 1 (/shop):
- Expired 30-day return window (
ORD-90125): Click Request refund for ORD-90125 (Expired 45d Window) (or type"Refund my sunglasses"). Step 1 infersorder_id = 90125(Polarized Aviator Titanium Sunglasses,$165.00), pauses for Turn 1 confirmation (PENDING_CONFIRMATION), and on Turn 2 denies the request withRETURN_WINDOW_EXPIRED(target_order_age_days = 45 > 30). - Order not yet delivered (
ORD-90126): Click Request refund for ORD-90126 (Shipped / In Transit) (or type"Refund my shipped order"). Step 1 infersorder_id = 90126(Cashmere Ribbed Winter Beanie,$58.00), pauses for Turn 1 confirmation (PENDING_CONFIRMATION), and on Turn 2 denies the request withORDER_NOT_DELIVERED(target_order_status = 'Shipped'). - Ambiguous order disambiguation (
resolution_mode = 'clarify') and negated refund (resolution_mode = 'cancelled'): Type a refund request with no order ID and no disambiguating cue (such as"I want a refund"), decline a confirmation prompt ("No, wrong order"), or state"No, I don't want to refund". The agent stays inPENDING_CONFIRMATIONand lists Alice's active non-returned orders as clickable candidate chips. - Unpurchased storefront product request (
unmatched_product): Request a refund or order lookup for a storefront catalog item that Alice never purchased (such as"I would like to refund Organic Supima Cotton Shirt order.").IntentAgentdetects that Organic Supima Cotton Shirt is not in Alice's order history, andResponseAgentexplains this clearly while offering her active orders (ORD-90126,ORD-90124,ORD-90125) as clickable candidate chips. - Conversational order list, status filtering, and selector follow-ups
(
ORDER_LIST,POLICY_INFO,ORDER_INFO): Ask"Show me the list of last 3 orders", then follow up with"What is the oldest order from the list?"or"What is the cheapest order from the list?"to resolve the exact single order (ORDER_INFOwith order and delivery dates). Asking"Which of my recent orders are completed?"displays only the 2'Complete'order cards (ORD-90124andORD-90125) matching the agent's reply.
Task 8. Test your knowledge¶
Answer the following questions to check your understanding of the lab concepts.