ag-ui-protocol / ag-ui-protocol/ag-ui

feat(ag-ui-adk): opt-in RAW passthrough of the untranslated ADK event

未關閉
#2,098 1 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement Integration
主要語言
Python
星號
15.9k
分支
1.4k
平均合併
1 天 17 小時
30 天內合併 PR
163

描述

## 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).

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。