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

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

Aperta
#2,098 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
enhancement Integration
Lingua principale
Python
Stelle
15.9k
Fork
1.4k
Merge medio
1g 17h
PR unite (30g)
163

Descrizione

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

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.