Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions python/packages/ag-ui/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
## Protocol Notes

- Outbound custom events are emitted as AG-UI `CUSTOM`.
- A2UI snapshot render calls retain explicit `parentToolCallId`; tool results retain emission order through cold hydration.
- Usage metadata from `Content(type="usage")` is surfaced as `CUSTOM` events with `name="usage"`.
- Text annotations are surfaced as `CUSTOM` events with `name="annotations"` and
`value={"messageId": ..., "annotations": [...]}`. Annotation-only updates announce a text message if needed
Expand Down
9 changes: 9 additions & 0 deletions python/packages/ag-ui/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -659,3 +659,12 @@ The package uses a clean, orchestrator-based architecture:
## License

MIT

### Nested A2UI snapshot replay

Saved A2UI render calls include the public `parentToolCallId` field identifying
the `generate_a2ui` invocation that executed the render subagent. Snapshot tool
results retain emission order, including retries that finish before their parent.
This metadata survives snapshot serialization and hydration; it does not export
private session continuation state. Consumers must not infer this relationship
for older calls from matching surface IDs or content.
11 changes: 10 additions & 1 deletion python/packages/ag-ui/agent_framework_ag_ui/_a2ui/_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -1175,8 +1175,17 @@ async def _run_generate_streaming(
live_render_call_id = self._first_render_call_id(cru)
# Forward each per-chunk update so the hosting loop paints the
# render_a2ui argument fragments progressively.
# The invocation site knows the parent; message proximity and
# surface IDs cannot establish this relationship on replay.
forwarded_contents = [copy.copy(content) for content in cru.contents]
for content in forwarded_contents:
if content.type == "function_call" and content.name == RENDER_A2UI_TOOL_NAME:
content.additional_properties = {
**content.additional_properties,
"ag_ui_parent_tool_call_id": call.call_id,
}
yield AgentResponseUpdate(
contents=cru.contents,
contents=forwarded_contents,
role=getattr(cru, "role", None),
message_id=getattr(cru, "message_id", None),
response_id=getattr(cru, "response_id", None),
Expand Down
86 changes: 30 additions & 56 deletions python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py
Original file line number Diff line number Diff line change
Expand Up @@ -2369,10 +2369,11 @@ def _append_segmented_snapshot_messages(flow: FlowState, all_messages: list[dict

Segments tracked during streaming record whether text came before or after
tool calls (issue #7223); tool results still follow the tool-call message
they answer. Anything not covered by segment tracking falls back to the
legacy grouping so no content is dropped.
they answer only for legacy segments without result positions. Tracked
results retain their emission position, including nested calls.
"""
emitted_call_ids: set[str] = set()
positioned_result_ids = {segment["result_id"] for segment in flow.snapshot_segments if segment.get("result_id")}

for segment in flow.snapshot_segments:
kind = segment["kind"]
Expand All @@ -2393,7 +2394,13 @@ def _append_segmented_snapshot_messages(flow: FlowState, all_messages: list[dict
# leftover path below rather than vanishing silently.
emitted_ids = {call["id"] for call in calls}
emitted_call_ids.update(emitted_ids)
all_messages.extend(result for result in flow.tool_results if result.get("toolCallId") in emitted_ids)
all_messages.extend(
result
for result in flow.tool_results
if result.get("toolCallId") in emitted_ids and result.get("id") not in positioned_result_ids
)
elif kind == "tool_results" and segment.get("result_id"):
all_messages.extend(result for result in flow.tool_results if result.get("id") == segment["result_id"])
elif kind == "reasoning":
all_messages.extend(entry for entry in flow.reasoning_messages if entry.get("id") == segment["id"])

Expand All @@ -2411,7 +2418,11 @@ def _append_segmented_snapshot_messages(flow: FlowState, all_messages: list[dict
# emitted above and then excluded from the final append below.
all_messages.extend(result for result in flow.tool_results if result.get("toolCallId") in leftover_ids)
emitted_call_ids.update(leftover_ids)
all_messages.extend(result for result in flow.tool_results if result.get("toolCallId") not in emitted_call_ids)
all_messages.extend(
result
for result in flow.tool_results
if result.get("toolCallId") not in emitted_call_ids and result.get("id") not in positioned_result_ids
)


def _build_messages_snapshot(
Expand Down Expand Up @@ -2496,59 +2507,22 @@ def _build_safe_point_messages_snapshot(
"""Build an intermediate snapshot without unfinalized text or reasoning."""
all_messages = list(snapshot_messages)
safe_call_ids = _safe_point_tool_call_ids(flow)
results_by_call_id: dict[str, list[dict[str, Any]]] = {}
for result in flow.tool_results:
call_id = result.get("toolCallId")
if call_id is not None:
results_by_call_id.setdefault(str(call_id), []).append(result)

emitted_call_ids: set[str] = set()
for segment in flow.snapshot_segments:
if segment.get("kind") != "tool_calls":
continue
calls = [
flow.tool_calls_by_id[call_id]
for call_id in segment.get("call_ids", [])
if call_id in safe_call_ids and call_id in flow.tool_calls_by_id
]
if not calls:
continue
all_messages.append(
{
"id": str(segment.get("id") or generate_event_id()),
"role": "assistant",
"tool_calls": [call.copy() for call in calls],
}
)
for call in calls:
call_id = str(call["id"])
emitted_call_ids.add(call_id)
all_messages.extend(results_by_call_id.get(call_id, []))

leftover_calls = [
call
for call in flow.pending_tool_calls
if (call_id := call.get("id")) is not None
and str(call_id) in safe_call_ids
and str(call_id) not in emitted_call_ids
# A completed child needs its declared parent even while the parent is
# still running. Only follow producer-recorded ancestry.
for call_id in list(safe_call_ids):
parent = flow.tool_calls_by_id.get(call_id, {}).get("parentToolCallId")
if parent in flow.tool_calls_by_id:
safe_call_ids.add(parent)
safe_flow = copy.copy(flow)
safe_flow.pending_tool_calls = [call for call in flow.pending_tool_calls if call.get("id") in safe_call_ids]
safe_flow.tool_calls_by_id = {
call_id: call for call_id, call in flow.tool_calls_by_id.items() if call_id in safe_call_ids
}
safe_flow.snapshot_segments = [
dict(segment) for segment in flow.snapshot_segments if segment.get("kind") in {"tool_calls", "tool_results"}
]
if leftover_calls:
all_messages.append(
{
"id": generate_event_id(),
"role": "assistant",
"tool_calls": [call.copy() for call in leftover_calls],
}
)
for call in leftover_calls:
call_id = str(call["id"])
emitted_call_ids.add(call_id)
all_messages.extend(results_by_call_id.get(call_id, []))

for call_id, results in results_by_call_id.items():
if call_id not in emitted_call_ids:
all_messages.extend(results)

safe_flow.reasoning_messages = []
_append_segmented_snapshot_messages(safe_flow, all_messages)
bounded_messages = _bound_host_payload_history(_persistable_host_payload_history(all_messages))
return MessagesSnapshotEvent(messages=_project_host_payload_history(bounded_messages)) # type: ignore[arg-type]

Expand Down
7 changes: 5 additions & 2 deletions python/packages/ag-ui/agent_framework_ag_ui/_run_common.py
Original file line number Diff line number Diff line change
Expand Up @@ -745,11 +745,14 @@ def _emit_tool_call(
)
)

tool_entry = {
tool_entry: dict[str, Any] = {
"id": tool_call_id,
"type": "function",
"function": {"name": content.name, "arguments": ""},
}
parent_call_id = content.additional_properties.get("ag_ui_parent_tool_call_id")
if isinstance(parent_call_id, str) and parent_call_id:
tool_entry["parentToolCallId"] = parent_call_id
flow.pending_tool_calls.append(tool_entry)
flow.tool_calls_by_id[tool_call_id] = tool_entry

Expand Down Expand Up @@ -907,7 +910,7 @@ def _emit_tool_result_common(
# A result closes the current tool-call segment: a later call opens a new
# one, so `call A -> result A -> call B` snapshots as two call/result pairs
# in stream order instead of grouping B with A (moonbox3's replay concern).
flow.snapshot_segments.append({"kind": "tool_results"})
flow.snapshot_segments.append({"kind": "tool_results", "result_id": message_id})

had_pending_predictive_updates = bool(predictive_handler and predictive_handler.pending_state_updates)
if predictive_handler:
Expand Down
85 changes: 85 additions & 0 deletions python/packages/ag-ui/tests/ag_ui/test_a2ui.py
Original file line number Diff line number Diff line change
Expand Up @@ -2503,3 +2503,88 @@ async def gen():
asyncio.run(_drive(A2UIAgent(inner, _RenderSub())))
assert inner.calls >= 2 # planner round(s) + a final narration turn
assert (seen_options[-1] or {}).get("tool_choice") == "none" # final turn: tools off


async def test_render_subagent_records_actual_parent_without_mutating_provider_content():
provider_content = Content.from_function_call(
call_id="inner",
name="render_a2ui",
arguments=json.dumps({"surfaceId": "s1", "components": [{"id": "root", "component": "Card"}]}),
)

class Render:
def get_response(self, *args, **kwargs):
async def stream():
yield ChatResponseUpdate(role="assistant", contents=[provider_content])

return stream()

runner = enable_a2ui(_GenerateOnceInner(), Render())
contents = [content async for update in runner.run("card", stream=True) for content in update.contents]
inner = next(content for content in contents if content.type == "function_call" and content.call_id == "inner")
assert inner.additional_properties["ag_ui_parent_tool_call_id"] == "g1"
assert "ag_ui_parent_tool_call_id" not in provider_content.additional_properties


async def test_nested_retry_public_snapshot_after_cold_restore(tmp_path):
from dataclasses import asdict

from agent_framework_ag_ui import AgentFrameworkAgent, AGUIThreadSnapshot, InMemoryAGUIThreadSnapshotStore
from agent_framework_ag_ui._snapshot_session import ThreadSnapshotSession

class RetrySub:
def __init__(self):
self.attempt = 0

def get_response(self, messages, *, stream=False, options=None):
self.attempt += 1
call_id = f"render-{self.attempt}"
components = [{"id": "bad" if self.attempt == 1 else "root", "component": "Card"}]

async def stream():
yield ChatResponseUpdate(
role="assistant",
contents=[
Content.from_function_call(
call_id=call_id,
name="render_a2ui",
arguments=json.dumps({"surfaceId": "same", "components": components}),
)
],
)

return stream()

store = InMemoryAGUIThreadSnapshotStore()
runner = A2UIAgent(_GenerateOnceInner(), RetrySub())
wrapper = AgentFrameworkAgent(agent=runner, snapshot_store=store)
events = [
event
async for event in wrapper.run(
{
"thread_id": "nested",
"run_id": "live",
"__ag_ui_snapshot_scope": "scope",
"messages": [{"id": "user", "role": "user", "content": "card"}],
}
)
]
results = [event.tool_call_id for event in events if event.type == "TOOL_CALL_RESULT"]
assert results == ["render-1", "render-2", "g1"]
stored = await store.get(scope="scope", thread_id="nested")
assert stored is not None
public = {key: value for key, value in asdict(stored).items() if key != "session_state"}
path = tmp_path / "public-snapshot.json"
path.write_text(json.dumps(public))
fresh_store = InMemoryAGUIThreadSnapshotStore()
await fresh_store.save(
scope="scope", thread_id="nested", snapshot=AGUIThreadSnapshot(**json.loads(path.read_text()))
)
cold = await ThreadSnapshotSession.open(store=fresh_store, scope="scope", thread_id="nested")
hydrated = [event async for event in cold.hydrate_events(run_id="cold")]
messages = next(event for event in hydrated if event.type == "MESSAGES_SNAPSHOT").model_dump(
by_alias=True, exclude_none=True
)["messages"]
assert [message["toolCallId"] for message in messages if message["role"] == "tool"] == results
calls = {call["id"]: call for message in messages for call in message.get("toolCalls", [])}
assert calls["render-1"]["parentToolCallId"] == calls["render-2"]["parentToolCallId"] == "g1"
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Copyright (c) Microsoft. All rights reserved.

"""Nested result order and public ancestry survive a serialized cold restore."""

import json
from dataclasses import asdict

from agent_framework import Content

from agent_framework_ag_ui import AGUIThreadSnapshot, InMemoryAGUIThreadSnapshotStore
from agent_framework_ag_ui._agent_run import _build_messages_snapshot, _build_safe_point_messages_snapshot
from agent_framework_ag_ui._run_common import FlowState, _emit_tool_call, _emit_tool_result
from agent_framework_ag_ui._snapshot_session import ThreadSnapshotSession


async def test_nested_results_preserve_order_and_ancestry_after_cold_restore():
flow = FlowState(message_id="outer-message")

def start(call_id, name, parent=None):
content = Content.from_function_call(call_id=call_id, name=name, arguments='{"surfaceId":"same"}')
if parent:
content.additional_properties["ag_ui_parent_tool_call_id"] = parent
_emit_tool_call(content, flow)

def finish(call_id):
_emit_tool_result(Content.from_function_result(call_id=call_id, result="canonical:" + call_id), flow)

start("outer", "generate_a2ui")
start("first", "render_a2ui", "outer")
finish("first")
safe = _build_safe_point_messages_snapshot(flow, []).model_dump(by_alias=True, exclude_none=True)["messages"]
assert {call["id"] for message in safe for call in message.get("toolCalls", [])} == {"outer", "first"}
assert [message["toolCallId"] for message in safe if message["role"] == "tool"] == ["first"]
start("second", "render_a2ui", "outer")
finish("second")
finish("outer")
start("independent", "render_a2ui")
finish("independent")
snapshot = _build_messages_snapshot(flow, []).model_dump(by_alias=True, exclude_none=True)["messages"]
sequence = []
for message in snapshot:
sequence.extend(call["id"] for call in message.get("toolCalls", []))
if message["role"] == "tool":
sequence.append("result:" + message["toolCallId"])
assert sequence == [
"outer",
"first",
"result:first",
"second",
"result:second",
"result:outer",
"independent",
"result:independent",
]
serialized = json.dumps(asdict(AGUIThreadSnapshot(messages=snapshot)))
store = InMemoryAGUIThreadSnapshotStore()
await store.save(scope="scope", thread_id="thread", snapshot=AGUIThreadSnapshot(**json.loads(serialized)))
cold = await ThreadSnapshotSession.open(store=store, scope="scope", thread_id="thread")
hydrated = [event async for event in cold.hydrate_events(run_id="cold")]
replay = next(event for event in hydrated if event.type == "MESSAGES_SNAPSHOT").model_dump(
by_alias=True, exclude_none=True
)["messages"]
assert replay == snapshot
calls = {call["id"]: call for message in replay for call in message.get("toolCalls", [])}
assert calls["first"]["parentToolCallId"] == calls["second"]["parentToolCallId"] == "outer"
assert "parentToolCallId" not in calls["independent"]
Loading