GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
adk-2.0 docs: document attributes.adk.* contract + schema_version in SDK.md
- Dominant language
- Python
- Stars
- 47
- Forks
- 21
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 33
Description
Parent tracker: #190 (v18 contract).
Wave: 6 — Docs.
Blocked by: Wave 1 (#194, #195), Wave 2 producer-emission issues (#196-#205), **the design sub-issues that may add or shape fields in the `attributes.adk.*` contract: #203 (route/render_ui_widgets/rewind_before_invocation_id capture-or-defer decision) and #208 (oversized AGENT_STATE_CHECKPOINT offload field shapes), and #211 (the existing `TOOL_COMPLETED` typed-view shape decision lands here)**. Docs cannot close until those land or are explicitly deferred.
## Contract
Document the `attributes.adk.*` contract as the supported producer-consumer interface. Include:
- The full field inventory. **Inventory must be re-read against #203, #208, and #211 outcomes before docs close** — those issues can add `attributes.adk.route`, `attributes.adk.render_ui_widgets`, `attributes.adk.rewind_before_invocation_id`, `attributes.adk.agent_state_uri`, `attributes.adk.agent_state_sha256`, and the inline `content.agent_state` stub shape, and can decide whether the existing `TOOL_COMPLETED` typed view exposes `attributes.adk.{function_call_id, pause_kind, pause_orphan}` or routes consumers to `long_running_tool_durations` / base-table JSON. Today's known fields: `schema_version`, `app_name`, `source_event_id`, `node.{path, run_id, parent_path, output_for, message_as_output}`, `branch`, `scope`, `pause_kind`, `pause_orphan`, `function_call_id`, `otel_span_id`.
- Per-field semantics, types, and which rows carry them (every enriched / Event-originating / long-running-path).
- The `attributes.adk.schema_version` deprecation policy.
- Explicit statements that raw ADK `isolation_scope` is internal and not part of the public contract — consumers join on `attributes.adk.scope`.
- The `pause_orphan` drift-quantification contract and how `long_running_tool_durations` surfaces it (healthy pairs exclude orphans; orphan rows surface separately).
- The #211 decision for the existing `TOOL_COMPLETED` typed view: either the new ADK long-running columns are documented as part of the typed view, or the doc says explicitly that consumers must read those fields from `long_running_tool_durations` / base-table JSON.
## Acceptance
- [ ] `SDK.md` (or a dedicated `docs/adk-2.0-attributes.md`) contains the contract.
- [ ] Field inventory verified against #203's decision (captured fields included; deferred fields explicitly noted as deferred with rationale).
- [ ] Field inventory verified against #208's decision (offload field shapes documented if the decision is to capture; or noted as deferred).
- [ ] **#211's `TOOL_COMPLETED` typed-view decision is reflected** — either the typed-view extension is documented, or the doc states that long-running ADK fields are not on the typed view and lists `long_running_tool_durations` / base-table JSON as the consumer path.
- [ ] Cross-linked from `README.md` and `USER_GUIDE.md`.
- [ ] A reviewer unfamiliar with #190 can implement a consumer against `attributes.adk.*` from this doc alone.
## References
- #190 (v18 consumer section + every per-field decision in the revision history).
- #203 (`actions.route` / `render_ui_widgets` / `rewind_before_invocation_id` capture-or-defer).
- #208 (oversized `AGENT_STATE_CHECKPOINT` offload contract).
- #211 (existing `TOOL_COMPLETED` typed-view shape decision).
Contributor guide
Assessment
This issue has not been assessed yet.