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

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

Ouverte
#2,098 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub
enhancement Integration
Langage dominant
Python
Étoiles
15.9k
Forks
1.4k
Merge moyen
1 j 17 h
PR mergées (30 j)
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).

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.