Restructure BigQuery Agent Analytics doc for scannability

[caohy1988]

Summary

Full restructure of the BigQuery Agent Analytics plugin doc, addressing #1710. Two phases in one PR:

Phase 1 — Additive tables (no section moves)

• Captured-events summary table: 19-row table near the top listing all event types, when they fire, key fields, and corresponding view
• Configuration reference tables: Converted bullet list to two 4-column tables (constructor params + BigQueryLoggerConfig)
• Collapsible DDL: Production DDL wrapped in ??? example admonition
• Conversational Analytics: Demoted from standalone ## to ### under query section

Phase 2 — Structural reorder

• Shortened quickstart: Minimal 3-import example; full example with GCS/OTel/BigQuery tools moved to collapsible block
• Agent Runtime moved later: From position 4 (interrupting core narrative) to position 9 (after query recipes)
• GCS offloading extracted: From nested #### under "Event types" to its own ## Storage behavior: GCS offloading
• Query recipes regrouped by task: Debug a run, Monitor cost/performance, Inspect tools/interactions, Analyze multimodal, AI root cause, Conversational Analytics
• Operations consolidated: Tracing, Public methods, and Multiprocessing grouped under one ## Operations section
• New anchors: {#prerequisites}, {#configuration-options}

New section order

1. Overview + Use cases + Captured events
2. Quickstart (shortened)
3. Prerequisites + IAM
4. Configuration (tables)
5. Schema + Views
6. Event types + payloads
7. Storage behavior: GCS offloading
8. Query recipes (task-grouped)
9. Deploy to Agent Runtime
10. Security + redaction
11. Operations (tracing, methods, multiprocessing)
12. SDK / dashboards
13. Feedback + resources

Anchors

All 5 existing anchors preserved: #deploy-agent-runtime, #event-types, #hitl-events, #security-credentials, #built-in-redaction. Added: #prerequisites, #configuration-options.

Test plan

• Quickstart renders with minimal example + collapsible full example
• Captured-events table renders all 19 rows
• Config tables render correctly (constructor + BigQueryLoggerConfig)
• DDL is collapsible
• GCS offloading section renders correctly as standalone ##
• Query recipes show task-based ### grouping with #### subsections
• Agent Runtime section appears after query recipes
• Operations section groups tracing + public methods + multiprocessing
• All 7 anchors resolve correctly
• No broken internal cross-references

Ref: #1710

[netlify]

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	91dc2de
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/69f304f2c2ebff0008deff10
😎 Deploy Preview	https://deploy-preview-1711--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.

[caohy1988]

Found one small issue to tighten before merge:

• The new captured-events table says it "lists every event the plugin logs," but the HITL_*_COMPLETED row groups three concrete event types (HITL_CREDENTIAL_REQUEST_COMPLETED, HITL_CONFIRMATION_REQUEST_COMPLETED, HITL_INPUT_REQUEST_COMPLETED). Either expand that wildcard row into the three actual event rows, or change the intro wording to "event types and event families". The PR body/test-plan also says "17 event types," which has the same ambiguity.

Everything else in Phase 1 looks aligned: no section moves, the DDL admonition is low-risk, Conversational Analytics is now under query examples, and the known anchors still resolve (#deploy-agent-runtime, #event-types, #hitl-events, #security-credentials, #built-in-redaction). git diff --check is clean.

[caohy1988]

Phase 2 is directionally good; the new order is much easier to follow. I found two things I would fix before merge:

1. Quickstart may not be runnable with Vertex enabled. The shortened quickstart sets GOOGLE_GENAI_USE_VERTEXAI=True but no longer sets GOOGLE_CLOUD_LOCATION. The old full example did set it before Gemini construction, and the Gemini setup docs show it as part of Vertex configuration. Please add something like:

   os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"

   or avoid forcing Vertex mode in the minimal quickstart and point readers to the auth/model setup path. Since this is the first runnable snippet, it should not depend on an unstated env var.

2. Event types and payloads is still nested under Schema and production setup. The PR body says the new flow is Schema + Views followed by Event types + payloads, but the heading is still ### Event types and payloads {#event-types} after ## Schema and production setup, so the generated TOC will present event payloads as part of schema. I’d promote it to:

   ## Event types and payloads {#event-types}

   That preserves the existing anchor while matching the intended reader flow. The same applies conceptually to the section-order summary in the PR body.

Optional, but useful: add a tiny install/auth snippet before the quickstart code (google-adk[bigquery] requirements + gcloud auth application-default login) or explicitly say the commands are in Prerequisites. The quickstart is much shorter now, but it currently starts at code rather than setup.

I tried uv run mkdocs build --strict; the local env does not have mkdocs available, so I could not verify rendered output here. git diff --check origin/main...HEAD is clean.

[caohy1988]

Thanks, both review items are addressed:

• Quickstart now sets GOOGLE_CLOUD_LOCATION before constructing Gemini, so the Vertex path is explicit.
• Event types and payloads is now a top-level ## while preserving {#event-types}, and its child headings were promoted consistently.

I did one more source pass over anchors and internal links. The key explicit anchors are still present (#prerequisites, #configuration-options, #event-types, #hitl-events, #deploy-agent-runtime, #security-credentials, #built-in-redaction), and git diff --check origin/main...HEAD is clean.

No further blockers from me. I still could not run a full MkDocs render locally because this environment does not have mkdocs installed in the available uv context, so CI/render preview should be the final check for table/admonition layout.