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

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

Abierto
#2,098 1 comentario 0 reacciones 0 asignados Ver en GitHub
enhancement Integration
Lenguaje dominante
Python
Estrellas
15.9k
Forks
1.4k
Merge medio
1 d 17 h
PR fusionados (30 d)
163

Descripción

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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.