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

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

Aberta
#2,103 2 comentários 0 reações 0 responsáveis Ver no GitHub
enhancement Integration
Linguagem predominante
Python
Estrelas
15.9k
Forks
1.4k
Merge médio
1d 17h
PRs com merge (30d)
163

Descrição

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

Guia de contribuição

Abrir o guia de contribuição

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.