GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

adk-2.0 consumer: register six new event types across all SDK type surfaces

Open
#211 6 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 (v19 contract).
Wave: 4 — Consumer foundation.
Design dependency: #207 (workflow node-boundary derivation) — the typed-view column shapes for `WORKFLOW_NODE_STARTING` and `WORKFLOW_NODE_COMPLETED` are blocked until #207 picks OTel-span consumption vs event-observation derivation.

## Contract

This issue covers two SDK-surface changes that must land together so the typed consumer surface matches the producer contract:

### A. Register the six new event types across **every** event-type allowlist / categorization surface

Surfaces to audit and update (concrete list, not a "minimum" — implementers must audit the SDK and add to this list if they find more):

- `src/bigquery_agent_analytics/views.py::_EVENT_VIEW_DEFS` — **typed per-event-type views** for each new type, with extra columns extracting the documented `content` / `attributes` fields. Status per type:
- `AGENT_TRANSFER` — typed view from `content.{from_agent, to_agent}` (and optional `reason`). **Specifiable now from #200.**
- `EVENT_COMPACTION` — typed view from `content.{start_timestamp, end_timestamp, compacted_content}`. **Specifiable now from #201.**
- `AGENT_STATE_CHECKPOINT` — typed view from `content.{end_of_agent, agent_state}` (and offload fields from #208 once they land). **Specifiable now from #202 for the inline case; offload fields wait on #208.**
- `TOOL_PAUSED` — typed view from `attributes.adk.{function_call_id, pause_kind}`. **Specifiable now from #199.** `pause_orphan` is **not** a `TOOL_PAUSED` field — it lives on the long-running-path `TOOL_COMPLETED` row, addressed by Section B and by `long_running_tool_durations` (#215).
- `WORKFLOW_NODE_STARTING` / `WORKFLOW_NODE_COMPLETED` — **blocked by #207.** The producer-derivation strategy (OTel span consumption vs deterministic event-observation) determines the payload shape, so typed columns can't be specified yet. Until #207 lands, these two types are either registered with base-header-only views (no extra columns) or this issue's `_EVENT_VIEW_DEFS` work is split so #207's decision can extend `_EVENT_VIEW_DEFS` in a follow-up PR.
- `src/bigquery_agent_analytics/trace.py::EventType` enum.
- `src/bigquery_agent_analytics/event_semantics.py` categorization helpers.
- `src/bigquery_agent_analytics/trace_evaluator.py::_DEFAULT_EVENT_TYPES`.
- UDF label maps (e.g. `udf_kernels.py`).
- Any other event-type allowlist found in the audit.

### B. Update the existing `TOOL_COMPLETED` view shape for the long-running fields

`TOOL_COMPLETED` is **not a new event type**, so it won't be caught by the "six new types" audit. But #199 changes the **shape** of long-running-path `TOOL_COMPLETED` rows by adding `attributes.adk.{function_call_id, pause_kind, pause_orphan}`. The existing `tool_completions` view (`_EVENT_VIEW_DEFS["TOOL_COMPLETED"]`) currently extracts only content/latency fields and the standard headers — it doesn't expose those new ADK long-running fields.

Decide one of:
- (a) Extend the existing `TOOL_COMPLETED` view to expose `attributes.adk.function_call_id`, `attributes.adk.pause_kind`, `attributes.adk.pause_orphan` as typed columns. Null for non-long-running completions.
- (b) Leave the view as-is and document explicitly that consumers must read the long-running fields from `long_running_tool_durations` (#215) or from the base-table JSON. Document this in `SDK.md` (the #220 doc) so consumers don't expect the typed view to surface them.

Either is acceptable; the constraint is that the typed view contract is unambiguous and aligned with the producer contract.

## Acceptance

- [ ] All six new event types are present in every listed surface (enum / categorization / evaluator allowlist / UDF maps / `_EVENT_VIEW_DEFS`).
- [ ] Typed extra columns for `AGENT_TRANSFER`, `EVENT_COMPACTION`, `AGENT_STATE_CHECKPOINT` (inline), and `TOOL_PAUSED` (`function_call_id`, `pause_kind` — **not** `pause_orphan`) are defined per the originating producer sub-issues.
- [ ] `WORKFLOW_NODE_STARTING` / `WORKFLOW_NODE_COMPLETED` are registered (enum/allowlist) and have either base-header-only typed views with a TODO referencing #207, or are explicitly carved out as #207-follow-up work.
- [ ] Tests cover round-trip recognition of each new type through every surface.
- [ ] `TOOL_COMPLETED` view decision (extend vs document) is made and reflected in `SDK.md` (#220 acceptance).
- [ ] If (a): a test asserts long-running-path `TOOL_COMPLETED` rows expose the new ADK columns in the typed view.
- [ ] If (b): `SDK.md` says explicitly that long-running fields are not on the typed view.

## References

- #190 (v19 consumer SDK type surface; v9 broadened audit; v12 acceptance; v17 `_EVENT_VIEW_DEFS` + `TOOL_COMPLETED` shape; v18 #207 carve-out; v19 `pause_orphan` is `TOOL_COMPLETED`-only).
- #199 (producer adds `attributes.adk.{function_call_id, pause_kind}` to `TOOL_PAUSED`; adds `attributes.adk.{function_call_id, pause_kind, pause_orphan}` to long-running-path `TOOL_COMPLETED`).
- #207 (workflow node-boundary derivation — blocks node-boundary typed-view columns).
- #208 (state-offload contract — adds optional offload fields to the `AGENT_STATE_CHECKPOINT` typed view).
- `src/bigquery_agent_analytics/views.py::_EVENT_VIEW_DEFS["TOOL_COMPLETED"]`.

---

## Selected approach (v4) — split "now" vs "#207 follow-up"

Captured from the #297 v2 review thread.

### Now (this PR cycle)

Register the **four #293-shipped types** across the SDK type surfaces with full typed-view columns:

- `AGENT_TRANSFER` — typed columns from `content.{from_agent, to_agent}` (and optional `reason`). Source: #200.
- `EVENT_COMPACTION` — typed columns from `content.{start_timestamp, end_timestamp, compacted_content}`. Source: #201. Use `TIMESTAMP_MICROS(CAST( * 1000000 AS INT64))` to preserve fractional float-epoch precision.
- `AGENT_STATE_CHECKPOINT` (inline only) — typed columns from `content.{end_of_agent, agent_state}`. Source: #202. Offload columns (`agent_state_uri`, `agent_state_sha256`) wait on #208.
- `TOOL_PAUSED` — typed columns from `attributes.adk.{function_call_id, pause_kind}`. Source: #199 pair-key subset. **Do NOT include `pause_orphan`** — that field lives on long-running-path `TOOL_COMPLETED`, not on `TOOL_PAUSED`.

Extend the **existing `TOOL_COMPLETED` view** with the new ADK long-running fields:

- Add `attributes.adk.function_call_id`, `attributes.adk.pause_kind`, `attributes.adk.pause_orphan` as typed columns. Null on non-long-running completions.
- Document in `SDK.md` (#220) that null values are expected on non-long-running rows.

### Deferred to #207 follow-up

`WORKFLOW_NODE_STARTING` and `WORKFLOW_NODE_COMPLETED` typed-view columns are blocked by the workflow-boundary derivation choice in #207.

Until #207 lands:

- Register enum / categorization / allowlist entries for both types so consumers don't see "unknown" rows.
- Add base-header-only typed views with a `TODO: see #207` comment next to the empty extra-column list.

Once #207 lands (selected approach: event-observation derivation, invocation-segment scoped, ancestor pause propagation), extend the typed views with the documented columns in a follow-up PR.

### References

- #297 v2 — https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/297#issuecomment-4646897313
- #297 v4 — https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/297#issuecomment-4647000786

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.