docs(bqaa): align plugin docs with Python 2.7 and Java 1.7

[caohy1988]

Summary

Aligns the BigQuery Agent Analytics integration page with the released Python
2.7 and Java 1.7 plugin behavior. Developers now get accurate installation,
event/schema/view, delivery, redaction, tracing, and lifecycle guidance across
both SDKs.

This cumulative update carries forward the Java 1.7 documentation from the
closed review and adds the Python 2.7 schema and delivery changes now present on
adk-python/main.

Key decisions

• Default delivery remains best-effort. event_id is the consumer
  deduplication key, while exactly_once_delivery prevents ambiguous-retry
  duplicates within a live processor rather than guaranteeing lossless
  delivery.
• Drop counters distinguish lost rows from formatter/parser incidents that
  still write sentinel content.
• Language-specific behavior remains explicit where Python and Java differ,
  including workflow events, attribute locations, trace fallbacks, redaction,
  and lifecycle APIs.

Validation

• ./.venv/bin/mkdocs build --strict
• uvx --from codespell==2.4.1 codespell docs/integrations/bigquery-agent-analytics.md
• git diff --check
• Verified all 22 external links on the page return HTTP 200.
• Mechanically compared documented config fields, schema columns, event types,
  and view names with google/adk-python@4599a526 (main).

Related

Related: #1975

[netlify]

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	5f48f80
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/6a86abf9f1f22000088d0c25
😎 Deploy Preview	https://deploy-preview-2154--adk-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[caohy1988]

Full review — verified against google/adk-python@4599a526 and the v2.7.0 / v2.7.1 tags

Verdict: The PR is in very good shape — accurate, and materially better than what it replaces. I verified the doc's factual claims line-by-line against the actual plugin source at the pinned commit and the release tags. One likely-broken SQL snippet and one broken sentence; both easy fixes. Everything else checked matched the source exactly.

Issues to fix

1. The event_id dedup query will likely fail in BigQuery — QUALIFY requires a WHERE, GROUP BY, or HAVING clause (Delivery and deduplication section)

SELECT *
FROM `your-gcp-project-id.adk_agent_logs.agent_events`
QUALIFY
  event_id IS NULL
  OR ROW_NUMBER() OVER (PARTITION BY event_id ORDER BY timestamp) = 1;

BigQuery rejects a bare SELECT * FROM t QUALIFY … with "The QUALIFY clause requires at least one of these clauses: WHERE, GROUP BY, HAVING" — a long-standing, documented restriction. The conventional fix is to add WHERE TRUE before QUALIFY. Worth running the snippet once against a real table to confirm.

2. Broken sentence in the "Java attribute location" admonition. The em-dash cleanup rewrote the first half of the sentence but left the old continuation line behind:

The Java plugin writes the pair keys at the top level of attributes:
"attributes": {"pause_kind": "tool", "function_call_id": "call-789"}.
with no adk wrapper. In the base-table query below, …

"with no adk wrapper." is now a stranded fragment after a full stop. Suggested rewrite: "The Java plugin writes the pair keys at the top level of attributes, with no adk wrapper: "attributes": {…}. In the base-table query below, replace …"

Verified correct (against adk-python source)

• Packaging: the bigquery-analytics extra exists with exactly the four documented deps (google-cloud-bigquery, -bigquery-storage, -storage, pyarrow); pyarrow is absent from the gcp extra; the import error names the bigquery-analytics extra.
• Version gating: event_id, exactly_once_delivery, and NODE_OUTPUT/NODE_ERROR are all inside the v2.7.0 tag, so "Python v2.7.0 and later" is right. (The mainline event_id commit 4aa1a811 isn't an ancestor of the tag, but the release branch carries an equivalent cherry-pick — checked the tag's file content directly.)
• Config table: final_response_tool_names: frozenset[str] = frozenset(), flush_on_run_end: bool = True, exactly_once_delivery: bool = False all match, including the source_tool attribute on tool-sourced AGENT_RESPONSE.
• Drop reasons: all 13 Python reason strings exist verbatim in source, and the split between lost-row reasons and the two written-with-sentinel incident counters (formatter_failed → [FORMATTER_FAILED], content_parse_failed → [CONTENT_PARSE_FAILED]) matches the implementation. The 30-second rotation backoff is real (self._rotation_retry_at = now + 30.0).
• Redaction: the 20-key list matches _SENSITIVE_KEYS exactly, including hyphen/underscore normalization; only temp: is a redacted prefix (secret: genuinely has no special handling anymore); the text/URI sanitization claims (auth headers, bearer/basic, signed-URL params) match the regex battery in the source.
• Schema & views: event_id is the second schema field (matching the DDL placement), _SCHEMA_VERSION = "2", event_id is in the views' common columns; v_llm_response columns match in content and order (through cache_metadata, cache_type, finish_reason); v_agent_error / v_invocation_error / v_node_output / v_node_error columns match; A2A's content = a2a:response payload with namespaced keys under attributes.a2a_metadata matches.
• Semantics: NODE_OUTPUT gating (event.output present and message_as_output is not True), NODE_ERROR gating (error_code not in the LLM finish/block set), envelope fields route / render_ui_widgets / rewind_before_invocation_id, flush() being current-loop-scoped, and close() delegating to shutdown() — all confirmed.

Caveat

The Java-side claims (v1.7.0 gating for getDropStats / shutdown hook / redaction, the six-key Java redaction list, pre-1.7 plugin-owned OTel spans, top-level pair keys) weren't verifiable in this pass — no adk-java checkout at hand. They read consistent with the prior doc text, but if any weren't already reviewed in the closed Java-doc PR, a spot check against adk-java would close the loop.

One nice touch worth keeping: replacing the issue-#3845 credential warning with the honest "redaction is not DLP" framing is more accurate now that the sanitizer battery exists, without overpromising.

---

🤖 Review performed with Claude Code

[caohy1988]

The event_id dedup query will likely fail in BigQuery — QUALIFY requires a WHERE, GROUP BY, or HAVING clause.

Not changing this snippet. GoogleSQL's SELECT grammar makes WHERE, GROUP BY, and HAVING optional before QUALIFY; the QUALIFY requirement is that a window function appear in QUALIFY or the select list. I also validated the same query shape with bq query --use_legacy_sql=false --dry_run; it succeeded and reported 0 bytes processed.

Broken sentence in the "Java attribute location" admonition.

Addressed in 5f48f804: "with no adk wrapper" is now part of the opening sentence, and the JSON example no longer leaves a stranded fragment.

The Java-side behavioral claims were carried forward from the earlier Java-focused review in #1975; this follow-up does not expand them.