Commit e2676fc
feat(plugins): ADK 2.0 minimum producer cut for the BigQuery Agent Analytics plugin
Customer-driven minimum producer subset of the ADK 2.0 observability work: the
smallest set of event types and `attributes.adk.*` envelope fields a customer
needs in BigQuery to take ADK 2.0 to production. Producer-only and strictly
additive — no BigQuery row-schema column changes; consumers read base-table JSON.
What lands:
1. `attributes.adk.*` envelope on every ADK-enriched row.
- A1/A2: `schema_version` and `app_name` always.
- A3/C1/C2/C3: `source_event_id`, `node = {path, run_id, parent_run_id}`,
`branch`, `scope = null | {id, kind}` only on rows with an originating
Event. Callback-only rows omit these keys (never fabricated); an omitted
key resolves to SQL NULL via `JSON_VALUE(attributes, '$.adk.<field>')`.
- `node.run_id` / `node.parent_run_id` mirror ADK's `NodeInfo` `@property`
values (parsed from `node_info.path`), read explicitly rather than via
`model_dump`.
2. Four new event types from previously-unlogged `EventActions`/`Event`
surfaces:
- `AGENT_TRANSFER` (`from_agent = event.author`,
`to_agent = actions.transfer_to_agent`).
- `EVENT_COMPACTION` (fractional float-epoch seconds preserved).
- `AGENT_STATE_CHECKPOINT` (both `{agent_state, end_of_agent}` shapes,
inline payload only).
- `TOOL_PAUSED` per `long_running_tool_id`, with HITL-aware `pause_kind`
(via `_HITL_PAUSE_KIND_MAP`, derived from the function-call NAME) and a
`function_call_id` pair key; plus an unmatched-id fallback row.
3. Pair-key resume path: a non-HITL `function_response` arriving in a user
message emits `TOOL_COMPLETED` with `attributes.adk.{pause_kind='tool',
function_call_id}` so the `TOOL_PAUSED` ↔ `TOOL_COMPLETED` join works in
plain SQL.
4. HITL routing preserved: HITL `function_response`s continue routing to
`HITL_*_COMPLETED` only, never `TOOL_COMPLETED`.
5. Action-attribute mirror: `attributes.adk.{route, render_ui_widgets,
rewind_before_invocation_id}` (flat-with-prefix).
6. Cleanup: delete the deprecated, never-invoked `on_state_change_callback`
stub.
`_EVENT_VIEW_DEFS` is extended for the four new types (and `TOOL_COMPLETED`
gains the pair keys), so the plugin's per-event-type views expose the new
fields. `AGENT_RESPONSE` retains its legacy flat `source_event_*` extras for
backward compatibility alongside the canonical `attributes.adk.*` envelope.
Deferred (tracked separately): dedicated `WORKFLOW_NODE_STARTING/COMPLETED`
events, pause-registry `pause_orphan` semantics, oversized-state GCS offload,
OTel `otel_span_id`, and consumer typed views.
Ported from caohy1988#6, validated against current ADK HEAD; uses
ADK's `NodeInfo.parent_run_id` for the node envelope's third key.
All paths covered by unit tests.
Co-authored-by: Haiyuan Cao <haiyuan@google.com>
PiperOrigin-RevId: 9295906731 parent 0c6974c commit e2676fc
2 files changed
Lines changed: 1031 additions & 44 deletions
File tree
- src/google/adk/plugins
- tests/unittests/plugins
0 commit comments