diff --git a/python/packages/ag-ui/AGENTS.md b/python/packages/ag-ui/AGENTS.md index 4db4e36b0b1..89b245fddc5 100644 --- a/python/packages/ag-ui/AGENTS.md +++ b/python/packages/ag-ui/AGENTS.md @@ -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 diff --git a/python/packages/ag-ui/README.md b/python/packages/ag-ui/README.md index 04e486b2bb6..dbee0048c60 100644 --- a/python/packages/ag-ui/README.md +++ b/python/packages/ag-ui/README.md @@ -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. diff --git a/python/packages/ag-ui/agent_framework_ag_ui/_a2ui/_agent.py b/python/packages/ag-ui/agent_framework_ag_ui/_a2ui/_agent.py index fd172b4f5f0..1477639d663 100644 --- a/python/packages/ag-ui/agent_framework_ag_ui/_a2ui/_agent.py +++ b/python/packages/ag-ui/agent_framework_ag_ui/_a2ui/_agent.py @@ -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), diff --git a/python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py b/python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py index f9090b0ed8d..592b960c68a 100644 --- a/python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py +++ b/python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py @@ -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"] @@ -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"]) @@ -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( @@ -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] diff --git a/python/packages/ag-ui/agent_framework_ag_ui/_run_common.py b/python/packages/ag-ui/agent_framework_ag_ui/_run_common.py index 9d080877d1b..c9511a7bae2 100644 --- a/python/packages/ag-ui/agent_framework_ag_ui/_run_common.py +++ b/python/packages/ag-ui/agent_framework_ag_ui/_run_common.py @@ -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 @@ -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: diff --git a/python/packages/ag-ui/tests/ag_ui/test_a2ui.py b/python/packages/ag-ui/tests/ag_ui/test_a2ui.py index 48495fddc15..092996e1fa2 100644 --- a/python/packages/ag-ui/tests/ag_ui/test_a2ui.py +++ b/python/packages/ag-ui/tests/ag_ui/test_a2ui.py @@ -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" diff --git a/python/packages/ag-ui/tests/ag_ui/test_nested_snapshot_provenance.py b/python/packages/ag-ui/tests/ag_ui/test_nested_snapshot_provenance.py new file mode 100644 index 00000000000..009a64dd594 --- /dev/null +++ b/python/packages/ag-ui/tests/ag_ui/test_nested_snapshot_provenance.py @@ -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"]