GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

adk-2.0 consumer: branch_fanout view (cardinality only; branch_concurrency deferred)

Open
#214 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 (v17 contract).
Wave: 5 — Consumer views.
Blocked by: #195 (`attributes.adk.app_name` + `attributes.adk.source_event_id` identity stamping — both grouped on and gated on), #197 (producer `attributes.adk.branch`), #210 (cross-event deployment plumbing).

## Contract

**First pass = cardinality only.** Per `(JSON_VALUE(attributes, '$.adk.app_name'), user_id, session_id, invocation_id)`, count distinct `attributes.adk.branch` values.

Concurrency is intentionally deferred — a meaningful concurrency metric requires interval data from `WORKFLOW_NODE_STARTING/COMPLETED`, which is still design-required (#207). Once that lands, add a `branch_concurrency` follow-up view.

### Row provenance gate

```sql
WHERE JSON_VALUE(attributes, '$.adk.source_event_id') IS NOT NULL
```

This excludes:
- Pre-2.0 rows (no `attributes.adk` block at all).
- Non-Event-originating callback rows in v2 (`USER_MESSAGE_RECEIVED`, before-model, before-tool, etc.).

`branch` is an ADK `Event` field, so only originating-Event rows have a meaningful read.

### Zero-branch policy

**Emit a row with `distinct_branch_count = 0`** for v2 Event-originating invocations that have no `attributes.adk.branch` on any row. This preserves the invocation in the analytical surface so consumers can compute "% of v2 invocations that branch" and similar metrics. The alternative (no row) would silently hide non-branched invocations from the analytic surface.

## Acceptance

- [ ] One row per `(app_name, user_id, session_id, invocation_id)` with `distinct_branch_count`.
- [ ] Gate uses `source_event_id IS NOT NULL`.
- [ ] **Zero-branch case**: a v2 Event-originating invocation with no branch on any row produces a row with `distinct_branch_count = 0` (not absent).
- [ ] Pre-2.0 rows excluded — no rows produced from invocations that only have pre-2.0 events.
- [ ] Non-Event-originating v2 rows excluded — they don't appear in the view.
- [ ] Follow-up `branch_concurrency` view is filed as a separate issue once #207 lands.

## References

- #190 (v17 consumer view 3; v6 concurrency deferral; v13 source_event_id gate pattern from `scope_cardinality`).

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.