ag-ui-protocol / ag-ui-protocol/ag-ui
feat(ag-ui-adk): opt-in RAW passthrough of the untranslated ADK event
- Dominant language
- Python
- Stars
- 15.9k
- Forks
- 1.4k
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 163
Description
## Summary
The AG-UI spec defines a `RAW` event (`RawEvent`: `type=RAW`, `event: Any`, `source?: string`) as an escape hatch for passing through the underlying, framework-native event. `ag-ui-adk` never emits it — the `EventTranslator` maps ADK `Event`s into the higher-level AG-UI vocabulary (`TEXT_MESSAGE_*`, `TOOL_CALL_*`, `STATE_*`, `REASONING_*`, …) and drops everything that doesn't fit those shapes.
That translation is the right default, but it means ADK-specific fields are invisible to the client:
- `event.actions` (`state_delta`, `transfer_to_agent`, `escalate`, `skip_summarization`, …)
- `event.custom_metadata` (incl. the `a2a:*` keys from `RemoteA2aAgent`)
- `event.grounding_metadata`, `event.usage_metadata`, `event.branch`, `event.long_running_tool_ids`
- partial/turn_complete flags, invocation ids, etc.
For **debugging** and **extensibility** (clients that want to react to ADK internals the translation doesn't carry), there's currently no way to see the raw event.
## Proposal
Add an **opt-in** `emit_raw_events: bool = False` flag to `ADKAgent`. When enabled, the `EventTranslator` emits a `RawEvent` carrying the untranslated ADK event (JSON-dumped, `source="google-adk"`) immediately **before** that event's translated AG-UI events. Off by default → zero behavior change for existing users; no per-event overhead unless enabled.
```python
agui_agent = ADKAgent(adk_agent=root_agent, emit_raw_events=True)
```
Wire shape:
```json
{ "type": "RAW", "event": { /* full ADK Event model_dump */ }, "source": "google-adk" }
```
## Notes
- Best-effort and non-fatal: a serialization failure is logged and swallowed so the RAW passthrough can never break the main stream.
- User events (already in the conversation) are skipped, as they are for translation.
- This is additive and orthogonal to every other transport/event feature.
Happy to send the PR (flag on `ADKAgent` + `EventTranslator`, plus tests).
Contributor guide
Assessment
This issue has not been assessed yet.