GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

adk-2.0 docs: document attributes.adk.* contract + schema_version in SDK.md

Open
#220 4 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.