GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

adk-2.0 docs: USER_GUIDE.md ADK 2.0 query recipes

Open
#221 2 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 (v17 contract).
Wave: 6 — Docs.
Blocked by: #212, #213, #214, #215, #216, #217 (consumer views) and #220 (schema/attributes doc).

## Contract

Add query recipes to `USER_GUIDE.md` for the five most common ADK 2.0 questions:

1. **Workflow tree**: reconstruct the DAG for an invocation from `workflow_invocations` (joining on `attributes.adk.node.parent_path`, not `parent_run_id`).
2. **Transfer chain**: list the ordered agent handoffs in an invocation from `agent_transfer_chains`.
3. **Long-running tool wall-clock**: per-tool elapsed time from `long_running_tool_durations`. **Recipe must explain the healthy/orphan split per #215**: healthy pairs filter to `pause_kind = 'tool' AND pause_orphan IS NOT TRUE` on the completed stream; orphan rows (`status = 'orphan_completion'`, null `pause_ts`) surface drift separately. Document why `pause_orphan` exclusion exists (write-time-vs-query-time visibility).
4. **Branch fanout**: per-invocation parallelism breadth from `branch_fanout`. **Recipe must explain the zero-branch row policy per #214**: v2 Event-originating invocations with no branch produce a `distinct_branch_count = 0` row (not absent), so "% of invocations that branch" works naturally.
5. **Compaction-aware token totals**: how to interpret `LLM_REQUEST` / `LLM_RESPONSE` cardinality alongside `compaction_windows`.

## Acceptance

- [ ] Each recipe is a runnable SQL block with explanatory prose.
- [ ] Each recipe uses the full telemetry identity in its joins/groups (`JSON_VALUE(attributes, '$.adk.app_name')`, `user_id`, `session_id`, `invocation_id` where applicable — per #190 v8 general identity rule).
- [ ] Long-running-tool recipe explicitly documents the `pause_orphan IS NOT TRUE` healthy-pair filter and how orphan rows surface drift.
- [ ] Branch-fanout recipe explicitly documents the zero-branch row policy.
- [ ] Recipes are cross-linked from #220's schema/attributes doc.

## References

- #190 (v17 consumer §4; v8 general identity rule; v17 healthy/orphan + branch_fanout semantics).
- #214 (zero-branch policy), #215 (healthy/orphan split), #220 (schema doc cross-link).

Contributor guide

Open the contributing guide

Research direction

Start in USER_GUIDE.md and read the contract in #190, then review #214, #215, and #220 for zero-branch, healthy/orphan, and schema semantics. Add five runnable SQL recipes with explanatory prose, full telemetry identity, the required orphan and zero-branch guidance, and a cross-link from #220; validate each recipe against the documented semantics.

Written by the indexing model from the issue text.

Assessment

Tech stack
sql
Domain
databases, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.