GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

adk-2.0 producer: thread source Event / node-info into EventData for non-on_event callbacks

Open
#194 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 (v15 contract).
Wave: 1 — Producer plumbing foundation (prerequisite for the whole producer-side enrichment story).

## Why this is a prerequisite

`EventData` (`src/google/adk/plugins/bigquery_agent_analytics_plugin.py:1949`) is currently a span/latency/model container — it does not carry the source `Event`. Only `on_event_callback` has the originating `Event`; the LLM and tool lifecycle callbacks operate on `CallbackContext` + `LlmRequest` / `LlmResponse` / tool args. As a result, every per-row enrichment in #190 (node, branch, scope, source_event_id, etc.) is currently feasible only on `on_event_callback` rows — which is not what the contract promises.

## Contract

Thread either the source `Event` reference itself, **or** a typed pre-extracted telemetry context struct, into `EventData` so `_log_event` can enrich uniformly across all callback paths.

If the implementation chooses the pre-extracted struct (e.g. `EventTelemetryContext`) rather than the whole `Event`, it must carry **at minimum** every event-derived field consumed by downstream sub-issues:

| Struct field | Consumed by |
|---|---|
| `event_id` | #195 (`attributes.adk.source_event_id`) |
| `node_info` (path + computed `run_id`, `parent_run_id`) | #196 (`attributes.adk.node`, `parent_path` derivation) |
| `branch` | #197 (`attributes.adk.branch`) |
| `isolation_scope` | #198 (`attributes.adk.scope` normalization) |
| `actions` | #200 (`AGENT_TRANSFER`), #201 (`EVENT_COMPACTION`), #202 (`AGENT_STATE_CHECKPOINT`), #203 (route/widgets/rewind), #205 (otel correlation) |
| `long_running_tool_ids` | #199 (`TOOL_PAUSED` emission) |
| `content` | #199 (matching `long_running_tool_id` back to `part.function_call.{id,name}`), #200 (transfer agent names if inferable), #207 design |
| `timestamp` | future event-derived views that need source-event timing |
| `custom_metadata` | A2A flow (existing `:3047`) and any future event-attached metadata |

If the implementation picks the "pass the whole `Event`" route, none of the above needs to be enumerated — the `Event` reference covers all of them. Either route is acceptable; the constraint is that the chosen interface cannot leave any downstream sub-issue impossible to implement cleanly.

Document the resulting per-callback coverage matrix:

| Callback | Has source Event / telemetry context after this change? |
|---|---|
| `on_event_callback` | Yes (already) |
| `before_model_callback` | TBD by this issue |
| `after_model_callback` | TBD by this issue |
| `before_tool_callback` | TBD by this issue |
| `after_tool_callback` | TBD by this issue |
| Others | TBD |

Until this issue lands, the contract elsewhere in #190 reads as: **node/branch/scope enrichment is best-effort and may be null on rows that don't have an originating `Event`.**

## Acceptance

- [ ] `EventData` exposes a typed slot for either the source `Event` reference or a telemetry context struct covering at minimum the fields listed above.
- [ ] Each callback that emits BQAA rows either populates this slot or has documented coverage gaps.
- [ ] Existing tests pass; no row-format regressions on pre-2.0 rows.
- [ ] Per-callback coverage matrix documented in the plugin module-level docstring.
- [ ] If the struct route is taken: a follow-up audit confirms #195, #196, #197, #198, #199, #200, #201, #202, #203, #205 can each read what they need from the struct.

## References

- `src/google/adk/plugins/bigquery_agent_analytics_plugin.py:1949` (`EventData` dataclass).
- `src/google/adk/plugins/bigquery_agent_analytics_plugin.py:2815` (`_log_event`).
- #190 (v15 producer §1 "Prerequisite (producer plumbing)").

Blocks: #195, #196, #197, #198, #199, #200, #201, #202, #203, #205 (anything that needs source-event context on non-`on_event` callbacks).

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.