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

feat(ag-ui-adk): emit ACTIVITY_SNAPSHOT/DELTA from ADK custom_metadata markers

Abierto
#2,103 2 comentarios 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

AG-UI defines `ACTIVITY_SNAPSHOT` / `ACTIVITY_DELTA` — a channel for surfacing background-task / progress "activity" distinctly from chat (snapshot = full content, delta = RFC 6902 JSON patch). Mastra maps its background-task lifecycle to these, and the A2A integration maps A2A task status-updates to them. `ag-ui-adk` never emits either, so an ADK agent has no way to show progress activity in the UI.

## The wrinkle

Unlike STEP (author/branch), interrupts (HITL pause) or RAW (the event itself), **ADK's event vocabulary has no native "activity" concept** — there's nothing to auto-derive it from. So emitting ACTIVITY requires an explicit producer signal.

## Proposal

Use a `custom_metadata` marker — the same channel `RemoteA2aAgent` already uses (`a2a:*` keys). A producer (tool, plugin, callback, or custom agent) tags an ADK event, and the translator turns it into ACTIVITY events. **Inherently opt-in**: no marker → nothing emitted → zero behavior change. No new flag needed.

```python
# snapshot (full content):
event.custom_metadata = {
"ag_ui.activity": {"message_id": "act_1", "activity_type": "web_search",
"content": {"query": "AG-UI", "status": "running"}}
}
# delta (RFC 6902 patch against a prior snapshot with the same message_id):
event.custom_metadata = {
"ag_ui.activity_delta": {"message_id": "act_1", "activity_type": "web_search",
"patch": [{"op": "replace", "path": "/status", "value": "done"}]}
}
```

The translator emits `ActivitySnapshotEvent` / `ActivityDeltaEvent` accordingly (either value may also be a list to emit several from one ADK event). `message_id` is auto-generated for a snapshot if omitted; required for a delta so it correlates. Malformed markers are skipped with a warning so a bad marker never breaks the stream.

## Scope

- Marker-gated, additive, orthogonal to SSE/WebSocket/httpBinary and every other event.
- The metadata-convention is deliberately minimal (mirrors `a2a:*`); a higher-level producer helper (e.g. an `emit_activity(...)` sugar bound to the run) could be a follow-up.

Happy to send the PR (translator support + 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.