bigquery-agent-analytics 0.3.2__tar.gz → 0.3.3__tar.gz

bigquery_agent_analytics-0.3.3/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "bqaa-tracing",
+  "description": "Claude Code tracing plugins for BigQuery Agent Analytics.",
+  "owner": {
+    "name": "Google LLC",
+    "url": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK"
+  },
+  "plugins": [
+    {
+      "name": "bigquery-agent-analytics-tracing",
+      "description": "Stream Claude Code hook traces to Google BigQuery Agent Analytics agent_events.",
+      "version": "0.1.0",
+      "source": "./plugins/claude_code_dist/bigquery-agent-analytics-tracing",
+      "author": {
+        "name": "Google LLC"
+      },
+      "homepage": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/plugins/claude_code",
+      "repository": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK",
+      "license": "Apache-2.0",
+      "keywords": [
+        "bigquery",
+        "agent-analytics",
+        "observability",
+        "tracing",
+        "claude-code"
+      ]
+    }
+  ]
+}

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.3}/.github/workflows/ci.yml

@@ -41,12 +41,18 @@ jobs:
       - name: Run autoformat and check for changes
         run: |
           bash autoformat.sh
-          if ! git diff --exit-code src/ tests/ examples/; then
+          if ! git diff --exit-code src/ tests/ examples/ scripts/; then
             echo ""
             echo "::error::Code is not formatted. Run 'bash autoformat.sh' and commit the changes."
             exit 1
           fi
 
+      - name: Check codelab notebook is in sync with markdown source
+        run: |
+          python scripts/generate_colab_from_codelab.py --check \
+            docs/codelabs/periodic_materialization.md \
+            examples/codelab/periodic_materialization/colab_notebook.ipynb
+
   test:
     name: Test (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.3}/.github/workflows/producers-ci.yml

@@ -19,11 +19,13 @@ on:
     branches: [main]
     paths:
       - 'producers/**'
+      - 'plugins/claude_code/**'
       - '.github/workflows/producers-ci.yml'
   pull_request:
     branches: [main]
     paths:
       - 'producers/**'
+      - 'plugins/claude_code/**'
       - '.github/workflows/producers-ci.yml'
 
 concurrency:
@@ -49,10 +51,10 @@ jobs:
         run: pip install "pyink>=24.3.0" "isort>=5.0"
 
       - name: isort --check
-        run: isort --check-only src/ tests/
+        run: isort --check-only src/ tests/ scripts/
 
       - name: pyink --check
-        run: pyink --check src/ tests/
+        run: pyink --check src/ tests/ scripts/
 
   test:
     name: Producers test (Python ${{ matrix.python-version }})
@@ -91,7 +93,19 @@ jobs:
       - name: Build sdist and wheel
         run: python -m build
 
-      - name: List artifacts
+      - name: List wheel/sdist
+        run: ls -la dist/
+
+      - name: Install built wheel for plugin build
+        # Make `importlib.metadata.version` resolve correctly so the
+        # plugin manifest gets a real version stamped in, not the
+        # pyproject fallback.
+        run: pip install dist/bigquery_agent_analytics_tracing-*.whl
+
+      - name: Build Claude Code plugin artifact
+        run: python scripts/build_claude_plugin.py
+
+      - name: List plugin artifact
         run: ls -la dist/
 
       - uses: actions/upload-artifact@v4

bigquery_agent_analytics-0.3.3/.github/workflows/release-tracing.yml

@@ -0,0 +1,220 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Release the `bigquery-agent-analytics-tracing` package and the
+# Claude Code plugin tarball.
+#
+# Trigger: push a `tracing-vX.Y.Z` tag whose version matches
+# `producers/pyproject.toml`'s `[project].version`. The tag namespace
+# is distinct from the root `vX.Y.Z` tags used by the consumption SDK
+# so the two release pipelines never collide.
+#
+# Pipeline:
+#   verify          - tag matches pyproject; run producer tests on 3.12
+#   build           - wheel + sdist + Claude Code plugin tarball
+#   github-release  - attach all artifacts to the GitHub release for
+#                     this tag, with auto-generated release notes
+#   publish-testpypi - upload wheel + sdist to TestPyPI via Trusted
+#                      Publishing (no secrets)
+#   publish-pypi    - same, to PyPI (gated by the `pypi` environment
+#                     so maintainers can require manual approval)
+#
+# Trusted Publishing setup (one-time, on the PyPI side):
+#   - https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+#   - Project: bigquery-agent-analytics-tracing
+#   - Owner:   GoogleCloudPlatform
+#   - Repo:    BigQuery-Agent-Analytics-SDK
+#   - Workflow: release-tracing.yml
+#   - Environment: testpypi / pypi (match the `environment:` blocks
+#     below). Until the project + trusted publisher are configured on
+#     TestPyPI/PyPI, the publish jobs will fail with a clear error —
+#     `build` and `github-release` still produce + attach artifacts so
+#     the release tag is not blocked.
+
+name: Release tracing
+
+on:
+  push:
+    tags:
+      - 'tracing-v*'
+
+concurrency:
+  group: release-tracing-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify version + tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: producers
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject version
+        id: version
+        run: |
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG="${GITHUB_REF_NAME#tracing-v}"
+          echo "Package version: ${PKG_VERSION}"
+          echo "Release tag:     ${GITHUB_REF_NAME} (extracted: ${TAG})"
+          if [ "${PKG_VERSION}" != "${TAG}" ]; then
+            echo "::error::Version mismatch: producers/pyproject.toml has ${PKG_VERSION} but tag is ${GITHUB_REF_NAME} (expected tracing-v${PKG_VERSION})"
+            exit 1
+          fi
+          echo "version=${PKG_VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Install producers with dev deps
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  build:
+    name: Build wheel + plugin tarball
+    runs-on: ubuntu-latest
+    needs: verify
+    defaults:
+      run:
+        working-directory: producers
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Install built wheel
+        # importlib.metadata.version() needs to see the dist-info so
+        # build_claude_plugin.py stamps the real version (not the
+        # pyproject fallback). Installing the wheel mirrors the
+        # producers-ci build path exactly.
+        run: pip install dist/bigquery_agent_analytics_tracing-*.whl
+
+      - name: Build Claude Code plugin tarball
+        run: python scripts/build_claude_plugin.py
+
+      - name: Verify all expected artifacts are present
+        run: |
+          ls -la dist/
+          test -f dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}.tar.gz \
+            || (echo "::error::missing sdist" && exit 1)
+          test -f dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}-py3-none-any.whl \
+            || (echo "::error::missing wheel" && exit 1)
+          test -f dist/bigquery-agent-analytics-tracing-claude-code-${{ needs.verify.outputs.version }}.tar.gz \
+            || (echo "::error::missing plugin tarball" && exit 1)
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: producers/dist/
+          if-no-files-found: error
+
+  github-release:
+    name: Create GitHub release
+    runs-on: ubuntu-latest
+    needs: [verify, build]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: dist/
+
+      - name: List downloaded artifacts
+        run: ls -la dist/
+
+      - name: Create release with artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "Tracing ${{ github.ref_name }}"
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+          files: |
+            dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}-py3-none-any.whl
+            dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}.tar.gz
+            dist/bigquery-agent-analytics-tracing-claude-code-${{ needs.verify.outputs.version }}.tar.gz
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    # Depend on github-release too: the plugin tarball ships ONLY as a
+    # GitHub release asset, so if that step fails we must not let the
+    # wheel/sdist reach PyPI. Otherwise the "wheel and plugin always
+    # go together" invariant from RELEASING.md breaks silently.
+    # publish-pypi inherits the guard transitively via needs: publish-testpypi.
+    needs: [verify, build, github-release]
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/bigquery-agent-analytics-tracing
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: dist/
+
+      - name: Strip non-PyPI artifacts
+        # The plugin tarball is a release artifact, not a PyPI
+        # distribution. Filename uses hyphens in
+        # 'bigquery-agent-analytics-tracing-claude-code-*' so it's
+        # distinguishable from the underscore-named sdist.
+        run: |
+          rm -f dist/bigquery-agent-analytics-tracing-claude-code-*.tar.gz
+          ls -la dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [verify, publish-testpypi]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bigquery-agent-analytics-tracing
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: dist/
+
+      - name: Strip non-PyPI artifacts
+        run: |
+          rm -f dist/bigquery-agent-analytics-tracing-claude-code-*.tar.gz
+          ls -la dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.3}/.github/workflows/release.yml

@@ -18,9 +18,19 @@ on:
   release:
     types: [published]
 
+# The release event has no tag-pattern filter, so any published
+# release fires this workflow. The producer pipeline publishes
+# `tracing-vX.Y.Z` releases (release-tracing.yml); without this
+# guard, every producer release would also trigger root SDK
+# publishing and fail version verification.
+#
+# Root SDK tags use the plain `vX.Y.Z` pattern; producer tags use
+# `tracing-vX.Y.Z`. Only the root pattern starts with literal `v`,
+# so this is an unambiguous boundary.
 jobs:
   build:
     name: Build package
+    if: startsWith(github.event.release.tag_name, 'v')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.3}/CHANGELOG.md

@@ -7,6 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-06-08
+
+### Release highlights
+
+Schema-derived Context Graph materialization, end to end. `bqaa context-graph
+--property-graph property_graph.sql` now derives the ontology + binding from the
+property graph plus live table schemas, so rename-free graphs need no
+hand-written `ontology.yaml` / `binding.yaml` — and the same one-artifact flow
+reaches the scheduled production path (Cloud Run deploy script, image builder,
+`run_job.py`, and the Terraform module), with a split read-only-events /
+writable-graph dataset contract. Explicit `--ontology` / `--binding` is retained
+as the advanced override for descriptions, inheritance, derived properties,
+renames, and the migration-v5 compiled-extractor path.
+
+### Added
+
+- **Schema-derived (`--property-graph`) materialization, local → production**
+  (local: [#277](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/277)
+  via [#278](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/278)–[#281](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/281),
+  [#285](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/285),
+  [#287](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/287);
+  deploy: [#286](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/286)
+  via [#288](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/288)–[#292](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/292))
+  — `bqaa context-graph --property-graph property_graph.sql` derives the ontology
+  + binding from the property graph + live table schemas, so no hand-written
+  `ontology.yaml` / `binding.yaml` is needed for rename-free graphs. Scheduled
+  production reaches parity: the Cloud Run deploy script, image builder,
+  `run_job.py` (`BQAA_PROPERTY_GRAPH`), and the Terraform module all accept the
+  one-artifact flow (placeholdered `property_graph.sql` + sibling
+  `table_ddl.sql`), with a split read-only-events / writable-graph contract
+  (events read-only; graph tables + `_bqaa_materialization_state` land in the
+  graph dataset). Explicit `--ontology`/`--binding` is preserved as the advanced
+  override (descriptions, inheritance, derived properties, renames, the
+  migration-v5 compiled extractor).
+- **Selectable `AI.GENERATE` extraction model**
+  ([#298](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/298))
+  — choose the model for the `ai-fallback` extraction across every surface:
+  `run_materialize_window(endpoint=...)` (Python API), `bqaa context-graph
+  --endpoint` (CLI), and `BQAA_ENDPOINT` for the scheduled `run_job.py` deploy.
+  Short names resolve to the Vertex `locations/global` publisher URL, so Gemini
+  3.x models such as `gemini-3.5-flash` work. Defaults to `gemini-2.5-flash`
+  everywhere, so existing callers are unaffected; ignored under
+  `--extraction-mode=compiled-only` (no AI call is made).
+
+### Fixed
+
+- **`run_job.py` table-DDL bootstrap mis-split on statement boundaries**
+  ([#286](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/286))
+  — `_bootstrap_entity_tables` split the DDL on `;` without accounting for
+  comments or quoting, so a `;` inside a `--` comment (e.g. the codelab
+  `table_ddl.sql`'s "materializer fills automatically; they are required")
+  produced a comment-only fragment BigQuery rejected with "Unexpected end of
+  statement" — and a `;` or `--` inside a string literal
+  (`OPTIONS(description="has; semicolon")`, `DEFAULT 'a;b'`) or a backtick
+  identifier could corrupt a customer's DDL. Replaced with a quote- and
+  comment-aware splitter: it strips `--` line comments and `/* */` block
+  comments and splits on `;` only at the top level (never inside `'`, `"`, or
+  `` ` `` quoting). Found by a live `--property-graph` deploy smoke.
+
+### Changed
+
+- **Renamed the context-graph example for product-facing clarity**
+  ([#282](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/282))
+  — `examples/migration_v5/` → `examples/context_graph/` (the `migration_v5`
+  label was internal milestone bookkeeping). The scheduled-deploy entrypoints
+  move with it (`examples/context_graph/periodic_materialization/...`). The
+  demo's default BigQuery dataset is now `context_graph` (was `migration_v5_demo`)
+  and the Terraform example's graph dataset is `context_graph` (was
+  `migration_v5_graph`). The user-facing docs (blog, codelab, runbook, deploy +
+  Terraform READMEs) now lead with the one-artifact `property_graph.sql` path as
+  primary and frame explicit `ontology.yaml` / `binding.yaml` as the advanced
+  override. The previously executed demo notebook is archived as
+  `examples/_archive/context_graph_historical_notebook.ipynb`. **Action for
+  users:** update any deep links to `examples/migration_v5/...` and any reference
+  to the `migration_v5_demo` dataset.
+
 ## [0.3.2] - 2026-05-22
 
 ### Release highlights

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigquery-agent-analytics
-Version: 0.3.2
+Version: 0.3.3
 Summary: SDK for analyzing and evaluating agent traces stored in BigQuery.
 Author: Google LLC
 License-Expression: Apache-2.0

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.3}/docs/README.md

@@ -61,7 +61,7 @@ architecture, rationale, and implementation plans behind key SDK features.
 
 | Document | Description |
 |----------|-------------|
-| [Migration v5 periodic materialization playbook](../examples/migration_v5/periodic_materialization/README.md) | Customer deployment path for keeping the MAKO migration v5 graph fresh on a schedule: local dry-run, Cloud Run Job + Cloud Scheduler deploy with `--smoke`, IAM matrix, schedule guidance, JSON log shape, Cloud Monitoring alert filters, state-table inspection, cleanup, and troubleshooting. |
+| [Context Graph periodic materialization playbook](../examples/context_graph/periodic_materialization/README.md) | Customer deployment path for keeping the MAKO context graph fresh on a schedule: local dry-run, Cloud Run Job + Cloud Scheduler deploy with `--smoke`, IAM matrix, schedule guidance, JSON log shape, Cloud Monitoring alert filters, state-table inspection, cleanup, and troubleshooting. |
 | [proposal_bigquery_agent_cli.md](proposal_bigquery_agent_cli.md) | CLI proposal and command design |
 | [python_udf_support_design.md](python_udf_support_design.md) | BigQuery Python UDF architecture |
 | [remote_function_rationale.md](remote_function_rationale.md) | Cloud Run remote function rationale |

bigquery_agent_analytics-0.3.3/docs/blog/periodic_materialization.md

@@ -0,0 +1,153 @@
+# Trace AI Agent Decisions with BigQuery Property Graphs
+
+**Byline**:
+
+
+*BigQuery property graphs, BigQuery Conversational Analytics, and the BigQuery Agent Analytics SDK are currently in Preview on Google Cloud. The BigQuery Agent Analytics Plugin is Generally Available (GA). Examples in this post use synthetic data.*
+
+Enterprises are rapidly deploying AI agents to transform their data platforms into proactive [Systems of Action](https://cloud.google.com/transform/shift-system-of-action-architecting-the-agentic-data-cloud-ai). However, scaling these mission-critical applications requires a reliable foundation of trust. Historically, systems of record focused on capturing what happened; in the agentic era, organizations must capture why it happened. When an auditor or executive asks "Why did the agent make that decision?", organizations need prompt, verifiable visibility into the agent's dynamic reasoning: its context, weighed options, exceptions granted, and final actions. Today, we are introducing Context Graph in BigQuery: an integrated solution that elevates standard agent telemetry into a structured, audit-ready graph of decisions. By capturing every action and linking it to its triggering context, Context Graph provides the transparent, reliable foundation you need to scale your System of Action with confidence.
+
+## The challenge of a trusted system of action
+
+AI agents provide a natural mechanism for reasoning over live data, orchestrating complex cross-system tasks, and driving proactive business outcomes. However, deploying autonomous agents for mission-critical applications at enterprise scale often presents the following challenges:
+
+* **Lack of transparency and trust:** As agents take actions on your behalf, it can be difficult to determine exactly why an agent made a specific decision, what data it touched, or whether you can confidently trust the outcome. Traditional data tools often just store the final outcome, suffering from an "amnesia" that loses the inputs, context, and synthesis that led to that specific action.
+
+* **Increased business risk:** Without clear, explainable visibility into automated actions, organizations are left vulnerable to potential monetary losses and internal policy violations. When an agent makes an anomalous choice, such as executing a transaction at an unexpected price, the inability to trace its root cause makes the system incredibly difficult to debug and reliably govern. Effective governance requires an auditable process to verify that guardrails are actually working.
+
+* **Unmanageable telemetry:** While tools like Google's Agent Development Kit (ADK) make it substantially easier to build and deploy agents, the raw traces they produce, such as event logs, tool calls, and reasoning steps, are inherently unstructured. This leaves the data difficult to query, hard to audit, and challenging to govern at scale. The valuable precedents buried in these logs are often lost, preventing the system from building a feedback loop to learn from past decisions.
+
+## Introducing Context Graph in BigQuery
+
+Context Graph in BigQuery transforms raw agent traces into a structured, trusted context, elevating flat telemetry into an interconnected, traversable web of decision traces, data lineage, and tool executions. Built on [BigQuery Agent Analytics](https://cloud.google.com/blog/products/data-analytics/introducing-bigquery-agent-analytics), which centralizes your Agent Development Kit (ADK) events directly in BigQuery, it connects every reasoning step to make automated decisions highly auditable. By doing so, it serves as a queryable "institutional memory" for your data platform, capturing the exceptions, overrides, and precedents that map how decisions are actually made.
+
+Crucially, this happens natively within your existing data warehouse; there is no need to export logs to a specialized graph database or build complex ETL pipelines. By providing this structured, easily queryable visibility, Context Graph helps organizations not just deploy a system of agents, but build a proactive system of action they can stand behind.
+
+![Context Graph architecture: an ADK agent's events flow through the BigQuery Agent Analytics Plugin into the agent_events table (raw telemetry); bqaa context-graph turns them into the agent_decisions_graph Context Graph (a structured decision trace); consumed via GQL / BigQuery Studio, Conversational Analytics, and by auditors, operators, and executives — with no external graph database](./images/context-graph-flow.png)
+
+## Context Graph in agentic media buying
+
+Consider digital media buying, where sell-side processes, like negotiating ad placements, evaluating pricing rules, and checking compliance, historically took weeks of manual handoffs and spreadsheet coordination. By deploying an autonomous Seller Agent, a digital media company can compress this entire lifecycle from months down to seconds. However, moving real advertising budgets at machine speed requires regulator-grade trust. If an executive or auditor asks why a specific live campaign was executed at a certain price point, digging through fragmented, raw system logs with ad-hoc SQL is the wrong control surface.
+
+By using BigQuery Context Graph, the company can verify that every automated decision is transparent and auditable. Every time the Seller Agent takes an action, the process is captured and structured automatically:
+
+* **Capturing the action:** The moment the agent queries a knowledge graph, hands a task to a specialized brand-safety sub-agent, or evaluates an inventory pricing rule, the event is captured natively by the BigQuery Agent Analytics plugin.
+
+* **Structuring the trace:** Instead of dumping these details into messy text logs, the system shapes the raw telemetry into a typed, queryable Context Graph based on the company's provided ontology.
+
+* **Answering the audit:** If a campaign's parameters need to be verified, compliance teams can traverse the resulting graph to see exactly which active contracts, floor prices, and brand safety rules triggered that specific execution.
+
+By turning flat log files into an interconnected relationship map, the company doesn't just run a fast system, it has a strictly governed, trusted system of action.
+
+## Let's walk through an example
+
+The example below uses the same generic agent decision flow the [hands-on codelab](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/codelabs/periodic_materialization.md) runs end to end: a request comes in, the agent weighs options with confidence scores, and an outcome is committed. Everything runs natively in BigQuery.
+
+### Step 1: Capture agent traces
+
+In production, the Generally Available BigQuery Agent Analytics Plugin captures agent activity (tool calls, LLM requests, approvals) the moment your ADK agent runs and stream-writes it to a structured `agent_events` table:
+
+```py
+from google.adk.plugins import BigQueryAgentAnalyticsPlugin
+
+plugin = BigQueryAgentAnalyticsPlugin(
+    project_id="your-project-id",
+    dataset_id="agent_analytics",
+)
+runner = Runner(agent=root_agent, plugins=[plugin])
+```
+
+To follow along without an agent, the SDK ships a generator that writes a realistic, production-shaped corpus directly to `agent_events`:
+
+```bash
+bqaa seed-events \
+    --project-id "$PROJECT_ID" --dataset-id "$DATASET" \
+    --scenario decision-realistic --seed 42
+```
+
+### Step 2: Define the context graph
+
+Declare the graph shape once, in standard SQL. This models the decision flow: requests, the options each request weighed, the committed outcome, and the edges that connect them.
+
+```sql
+CREATE OR REPLACE PROPERTY GRAPH agent_analytics.agent_decisions_graph
+  NODE TABLES (
+    agent_analytics.decision_request AS decision_request
+      KEY (request_id)
+      LABEL DecisionRequest PROPERTIES (request_id, request_text, requested_at),
+    agent_analytics.decision_option AS decision_option
+      KEY (option_id)
+      LABEL DecisionOption PROPERTIES (option_id, option_label, confidence),
+    agent_analytics.decision_outcome AS decision_outcome
+      KEY (outcome_id)
+      LABEL DecisionOutcome PROPERTIES (outcome_id, status, rationale, decided_at)
+  )
+  EDGE TABLES (
+    agent_analytics.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,
+    agent_analytics.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
+  );
+```
+
+### Step 3: Extract context graph from agent traces
+
+A single command reads the raw `agent_events` and populates the graph tables. It derives what to extract directly from the property graph you defined in Step 2: `bqaa context-graph` reads that `CREATE PROPERTY GRAPH` definition and the schemas of the tables it references, so the property-graph schema is the only thing you author — no separate ontology or binding file. For local development, run the materializer once:
+
+```bash
+bqaa context-graph \
+    --project-id "$PROJECT_ID" --dataset-id "$DATASET" \
+    --property-graph property_graph.sql \
+    --lookback-hours 24
+```
+
+For production, run the same materialization path on a schedule with the SDK's Cloud Run Job + Cloud Scheduler [deployment guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/context_graph/periodic_materialization) or Terraform module.
+
+Extraction is your choice: an LLM path (`AI.GENERATE`) for flexible onboarding against variable log structures, or a deterministic compiled mode (`--extraction-mode=compiled-only`) for lower cost and reproducible, auditor-verifiable output with no Vertex AI dependency. (Need descriptions, inheritance, derived properties, or column renames? Author an explicit `ontology.yaml` + `binding.yaml` and pass `--ontology`/`--binding` instead.)
+
+### Step 4: Access the context graph
+
+The graph is now queryable two ways. For exact, repeatable lineage, traverse it with Graph Query Language (GQL):
+
+```sql
+SELECT *
+FROM GRAPH_TABLE (
+  agent_analytics.agent_decisions_graph
+  MATCH
+    (req:DecisionRequest) -[:evaluatesOption]-> (opt:DecisionOption),
+    (req)                 -[: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
+  )
+)
+ORDER BY request, score DESC;
+```
+
+BigQuery Studio can also render the property graph visually. A `GRAPH … MATCH p = (a)-[e]->(b) RETURN TO_JSON(p)` query draws the full decision web:
+
+![The materialized decision graph (527 nodes, 438 edges) visualized in BigQuery Studio from a GQL query](./images/graph-visualization.png)
+
+For the business reader who does not write SQL, **BigQuery Conversational Analytics** (Preview) answers the same questions in plain English over the graph, generating the query for you:
+
+![Conversational Analytics summarizing the materialized decision graph in plain English: every recorded decision request reached a committed outcome (orphaned sessions are not materialized as graph nodes)](./images/ca-conversation.png)
+
+Ask in plain English first; drop to GQL when an answer needs to become a saved query, a scheduled report, or an audit artifact. The [Conversational Analytics-first guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/guides/conversational-analytics-first.md) walks through that workflow.
+
+## Get started
+
+To begin building Context Graphs for your agent workloads, check out the resources below:
+
+* **Code Repository**: Visit the [BigQuery Agent Analytics SDK on GitHub](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK).
+* **Hands-on Codelab**: Follow the step-by-step *Trace AI Agent Decisions with BigQuery Property Graphs* codelab to build and query a Context Graph from scratch.
+* **Production Setup**: Review the [Periodic Materialization guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/context_graph/periodic_materialization) to configure IAM, the Cloud Run Job, and the Cloud Scheduler trigger.
+* **Ask in plain English**: The [Conversational Analytics-first guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/guides/conversational-analytics-first.md) shows business readers how to query the decision graph without writing SQL.