Skip to content

Commit 26b9200

Browse files
jstar0moonbox3
andauthored
Python: Preserve AG-UI tool message IDs across snapshots (#7510)
* fix(ag-ui): preserve streamed tool message IDs * fix(ag-ui): align approval and MCP tool message IDs * fix(ag-ui): ensure unique tool segment IDs * fix(ag-ui): keep tool and text snapshot IDs unique --------- Co-authored-by: Evan Mattson <[email protected]>
1 parent e2938f4 commit 26b9200

3 files changed

Lines changed: 131 additions & 23 deletions

File tree

‎python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@
8686
_has_only_tool_calls, # type: ignore
8787
_iterate_with_context, # type: ignore
8888
_normalize_resume_interrupts, # type: ignore
89+
_new_tool_call_segment_id, # type: ignore
8990
_reconstruct_messages_from_thread_snapshot, # type: ignore
9091
_resume_contract_error, # type: ignore
9192
_resolve_ui_payload, # type: ignore
@@ -2002,11 +2003,6 @@ def _append_segmented_snapshot_messages(flow: FlowState, all_messages: list[dict
20022003
they answer. Anything not covered by segment tracking falls back to the
20032004
legacy grouping so no content is dropped.
20042005
"""
2005-
text_message_ids = {segment["id"] for segment in flow.snapshot_segments if segment["kind"] == "text"}
2006-
# A tool-only opening message (TextMessageStart with no text segment) lets
2007-
# the first tool-call message reuse the streamed message id, matching the
2008-
# legacy layout; every other tool message gets a fresh id.
2009-
tool_open_id = flow.message_id if flow.message_id and flow.message_id not in text_message_ids else None
20102006
emitted_call_ids: set[str] = set()
20112007

20122008
for segment in flow.snapshot_segments:
@@ -2020,8 +2016,8 @@ def _append_segmented_snapshot_messages(flow: FlowState, all_messages: list[dict
20202016
]
20212017
if not calls:
20222018
continue
2023-
message_id = tool_open_id or generate_event_id()
2024-
tool_open_id = None
2019+
message_id = str(segment.get("id") or _new_tool_call_segment_id(flow))
2020+
segment["id"] = message_id
20252021
all_messages.append({"id": message_id, "role": "assistant", "tool_calls": [call.copy() for call in calls]})
20262022
# Only mark the calls we actually emitted; a stale segment id that
20272023
# never made it into tool_calls_by_id must stay eligible for the
@@ -2037,7 +2033,7 @@ def _append_segmented_snapshot_messages(flow: FlowState, all_messages: list[dict
20372033
leftover_ids = {cid for call in leftover_calls if (cid := call.get("id")) is not None}
20382034
all_messages.append(
20392035
{
2040-
"id": tool_open_id or generate_event_id(),
2036+
"id": _new_tool_call_segment_id(flow),
20412037
"role": "assistant",
20422038
"tool_calls": [call.copy() for call in leftover_calls],
20432039
}
@@ -2784,10 +2780,11 @@ async def run_agent_stream(
27842780

27852781
# Emit confirm_changes tool call
27862782
confirm_id = generate_event_id()
2783+
confirm_message_id = _track_tool_call_segment(flow, confirm_id)
27872784
yield ToolCallStartEvent(
27882785
tool_call_id=confirm_id,
27892786
tool_call_name="confirm_changes",
2790-
parent_message_id=flow.message_id,
2787+
parent_message_id=confirm_message_id,
27912788
)
27922789
confirm_args = {
27932790
"function_name": tool_name,
@@ -2809,7 +2806,6 @@ async def run_agent_stream(
28092806
flow.pending_tool_calls.append(confirm_entry)
28102807
flow.tool_calls_by_id[confirm_id] = confirm_entry
28112808
flow.tool_calls_ended.add(confirm_id) # Mark as ended since we emit End event
2812-
_track_tool_call_segment(flow, confirm_id)
28132809
flow.waiting_for_approval = True
28142810
flow.interrupts.append(
28152811
_approval_interrupt_for_function_call(

‎python/packages/ag-ui/agent_framework_ag_ui/_run_common.py‎

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -550,12 +550,28 @@ def _text_segment_for(flow: FlowState, message_id: str) -> dict[str, Any] | None
550550
return None
551551

552552

553-
def _track_tool_call_segment(flow: FlowState, tool_call_id: str) -> None:
554-
"""Record a tool call in the current tool segment, opening one if needed."""
553+
def _new_tool_call_segment_id(flow: FlowState) -> str:
554+
"""Allocate a snapshot ID, reusing a tool-only opening ID at most once."""
555+
segment_ids = {segment.get("id") for segment in flow.snapshot_segments if segment.get("id")}
556+
if flow.message_id and flow.message_id not in segment_ids:
557+
return flow.message_id
558+
message_id = generate_event_id()
559+
while message_id in segment_ids:
560+
message_id = generate_event_id()
561+
return message_id
562+
563+
564+
def _track_tool_call_segment(flow: FlowState, tool_call_id: str) -> str:
565+
"""Record a tool call and return the message ID used by its stream events."""
566+
segment: dict[str, Any]
555567
if flow.snapshot_segments and flow.snapshot_segments[-1]["kind"] == "tool_calls":
556-
flow.snapshot_segments[-1]["call_ids"].append(tool_call_id)
568+
segment = flow.snapshot_segments[-1]
569+
segment.setdefault("id", _new_tool_call_segment_id(flow))
557570
else:
558-
flow.snapshot_segments.append({"kind": "tool_calls", "call_ids": [tool_call_id]})
571+
segment = {"kind": "tool_calls", "id": _new_tool_call_segment_id(flow), "call_ids": []}
572+
flow.snapshot_segments.append(segment)
573+
segment["call_ids"].append(tool_call_id)
574+
return str(segment["id"])
559575

560576

561577
def _track_reasoning_segment(flow: FlowState, message_id: str) -> None:
@@ -585,6 +601,19 @@ def _emit_text(content: Content, flow: FlowState, skip_text: bool = False) -> li
585601
logger.debug("Skipping duplicate full-text delta for message_id=%s", flow.message_id)
586602
return []
587603

604+
# A tool-only response may pre-open a message before its tool-call segment
605+
# is tracked. If that segment claims the pre-opened ID, rotate to a fresh
606+
# text message before recording the text so snapshot IDs stay unique.
607+
current_message_id = flow.message_id
608+
if current_message_id and any(
609+
segment.get("kind") == "tool_calls" and segment.get("id") == current_message_id
610+
for segment in flow.snapshot_segments
611+
):
612+
flow.message_id = generate_event_id()
613+
flow.accumulated_text = ""
614+
events.append(TextMessageEndEvent(message_id=current_message_id))
615+
events.append(TextMessageStartEvent(message_id=flow.message_id, role="assistant"))
616+
588617
# The message may have been pre-opened by the tool-only path, which never
589618
# goes through this function, so the first text arriving later has no
590619
# segment yet; without one the snapshot would drop it.
@@ -614,11 +643,12 @@ def _emit_tool_call(
614643
if predictive_handler:
615644
predictive_handler.reset_streaming()
616645

646+
tool_message_id = _track_tool_call_segment(flow, tool_call_id)
617647
events.append(
618648
ToolCallStartEvent(
619649
tool_call_id=tool_call_id,
620650
tool_call_name=content.name,
621-
parent_message_id=flow.message_id,
651+
parent_message_id=tool_message_id,
622652
)
623653
)
624654

@@ -629,7 +659,6 @@ def _emit_tool_call(
629659
}
630660
flow.pending_tool_calls.append(tool_entry)
631661
flow.tool_calls_by_id[tool_call_id] = tool_entry
632-
_track_tool_call_segment(flow, tool_call_id)
633662

634663
elif tool_call_id:
635664
flow.tool_call_id = tool_call_id
@@ -886,11 +915,12 @@ def _emit_approval_request(
886915

887916
if require_confirmation:
888917
confirm_id = generate_event_id()
918+
confirm_message_id = _track_tool_call_segment(flow, confirm_id)
889919
events.append(
890920
ToolCallStartEvent(
891921
tool_call_id=confirm_id,
892922
tool_call_name="confirm_changes",
893-
parent_message_id=flow.message_id,
923+
parent_message_id=confirm_message_id,
894924
)
895925
)
896926
args: dict[str, Any] = {
@@ -911,7 +941,6 @@ def _emit_approval_request(
911941
flow.pending_tool_calls.append(confirm_entry)
912942
flow.tool_calls_by_id[confirm_id] = confirm_entry
913943
flow.tool_calls_ended.add(confirm_id)
914-
_track_tool_call_segment(flow, confirm_id)
915944

916945
flow.waiting_for_approval = True
917946
return events
@@ -948,12 +977,13 @@ def _emit_mcp_tool_call(content: Content, flow: FlowState) -> list[BaseEvent]:
948977
tool_name = content.tool_name or "mcp_tool"
949978

950979
display_name = tool_name
980+
tool_message_id = _track_tool_call_segment(flow, tool_call_id)
951981

952982
events.append(
953983
ToolCallStartEvent(
954984
tool_call_id=tool_call_id,
955985
tool_call_name=display_name,
956-
parent_message_id=flow.message_id,
986+
parent_message_id=tool_message_id,
957987
)
958988
)
959989

@@ -973,7 +1003,6 @@ def _emit_mcp_tool_call(content: Content, flow: FlowState) -> list[BaseEvent]:
9731003
}
9741004
flow.pending_tool_calls.append(tool_entry)
9751005
flow.tool_calls_by_id[tool_call_id] = tool_entry
976-
_track_tool_call_segment(flow, tool_call_id)
9771006

9781007
return events
9791008

‎python/packages/ag-ui/tests/ag_ui/test_run.py‎

Lines changed: 86 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
import pytest
88
from ag_ui.core import (
99
CustomEvent,
10+
MessagesSnapshotEvent,
1011
ReasoningEncryptedValueEvent,
1112
ReasoningEndEvent,
1213
ReasoningMessageContentEvent,
@@ -17,6 +18,7 @@
1718
TextMessageEndEvent,
1819
TextMessageStartEvent,
1920
ToolCallArgsEvent,
21+
ToolCallStartEvent,
2022
)
2123
from agent_framework import AgentResponseUpdate, Content, Message, ResponseStream
2224
from agent_framework.exceptions import AgentInvalidResponseException
@@ -664,6 +666,24 @@ def test_snapshot_preserves_stream_order_around_tool_results():
664666
assert kinds[3][1]["id"] != kinds[0][1]["id"]
665667

666668

669+
def test_snapshot_reuses_streamed_tool_message_id_after_text():
670+
"""Tool-call snapshots reuse the stream ID used by the reference client merge."""
671+
flow = FlowState()
672+
_emit_text(Content.from_text("First, the plan."), flow)
673+
tool_events = _emit_tool_call(Content.from_function_call(call_id="call_1", name="docs_fetch", arguments="{}"), flow)
674+
tool_start = next(event for event in tool_events if isinstance(event, ToolCallStartEvent))
675+
_emit_tool_result(Content.from_function_result(call_id="call_1", result="done"), flow)
676+
_emit_text(Content.from_text("And the summary."), flow)
677+
678+
event = _build_messages_snapshot(flow, [])
679+
680+
kinds = _snapshot_kinds(event)
681+
assert [kind for kind, _ in kinds] == ["text", "tool_calls", "result", "text"]
682+
assert tool_start.parent_message_id is not None
683+
assert kinds[1][1]["id"] == tool_start.parent_message_id
684+
assert kinds[1][1]["id"] != kinds[0][1]["id"]
685+
686+
667687
def test_snapshot_tool_only_message_reuses_stream_message_id():
668688
"""Tool-only turns keep the message id the stream opened with."""
669689
flow = FlowState()
@@ -677,6 +697,27 @@ def test_snapshot_tool_only_message_reuses_stream_message_id():
677697
assert kinds[0][1]["id"] == "tool-only-msg"
678698

679699

700+
def test_snapshot_tool_only_segments_get_unique_ids_across_reasoning():
701+
"""A tool-only opening ID is consumed once across separated tool segments."""
702+
flow = FlowState(message_id="tool-only-msg")
703+
first_events = _emit_tool_call(
704+
Content.from_function_call(call_id="call_1", name="first_tool", arguments="{}"), flow
705+
)
706+
_emit_text_reasoning(Content.from_text("Thinking between calls."), flow)
707+
second_events = _emit_tool_call(
708+
Content.from_function_call(call_id="call_2", name="second_tool", arguments="{}"), flow
709+
)
710+
711+
snapshot = _build_messages_snapshot(flow, [])
712+
tool_messages = [message for kind, message in _snapshot_kinds(snapshot) if kind == "tool_calls"]
713+
first_start = next(event for event in first_events if isinstance(event, ToolCallStartEvent))
714+
second_start = next(event for event in second_events if isinstance(event, ToolCallStartEvent))
715+
716+
assert [message["id"] for message in tool_messages] == ["tool-only-msg", second_start.parent_message_id]
717+
assert first_start.parent_message_id == "tool-only-msg"
718+
assert second_start.parent_message_id != first_start.parent_message_id
719+
720+
680721
def test_snapshot_keeps_reasoning_in_emission_order():
681722
"""Reasoning blocks keep their streamed position instead of always trailing."""
682723
flow = FlowState()
@@ -706,20 +747,26 @@ def test_snapshot_without_segment_tracking_keeps_legacy_layout():
706747

707748

708749
def test_snapshot_includes_text_when_message_preopened_by_tool_only_path():
709-
"""Text that arrives after a tool-only preopen still lands in the snapshot."""
750+
"""Text after a tool-only preopen gets a unique snapshot message ID."""
710751
flow = FlowState()
711752
# The tool-only detection in agent_run.py preopens message_id without
712753
# going through _emit_text, so the first text has no segment yet.
713754
flow.message_id = "preopened"
714755
_emit_tool_call(Content.from_function_call(call_id="call_1", name="docs_fetch", arguments="{}"), flow)
715-
_emit_text(Content.from_text("Let me check the docs."), flow)
756+
text_events = _emit_text(Content.from_text("Let me check the docs."), flow)
716757

717758
event = _build_messages_snapshot(flow, [])
718759

719760
kinds = _snapshot_kinds(event)
720761
assert [kind for kind, _ in kinds] == ["tool_calls", "text"]
721762
assert kinds[1][1]["content"] == "Let me check the docs."
722-
assert kinds[1][1]["id"] == "preopened"
763+
assert kinds[0][1]["id"] == "preopened"
764+
assert kinds[1][1]["id"] != kinds[0][1]["id"]
765+
assert len({message["id"] for _, message in kinds}) == len(kinds)
766+
assert isinstance(text_events[0], TextMessageEndEvent)
767+
assert isinstance(text_events[1], TextMessageStartEvent)
768+
assert text_events[0].message_id == "preopened"
769+
assert text_events[1].message_id == kinds[1][1]["id"]
723770

724771

725772
def test_snapshot_separates_calls_across_results():
@@ -943,6 +990,26 @@ def test_emit_approval_request_populates_interrupt_metadata():
943990
}
944991

945992

993+
def test_emit_approval_request_reuses_confirmation_message_id_in_snapshot():
994+
"""Confirmation tool events and snapshots share the same message ID."""
995+
flow = FlowState()
996+
_emit_text(Content.from_text("Before approval."), flow)
997+
text_message_id = flow.message_id
998+
function_call = Content.from_function_call(call_id="call_123", name="write_doc", arguments={"content": "x"})
999+
approval_content = Content.from_function_approval_request(id="approval_1", function_call=function_call)
1000+
1001+
events = _emit_approval_request(approval_content, flow)
1002+
confirm_start = next(
1003+
event for event in events if isinstance(event, ToolCallStartEvent) and event.tool_call_name == "confirm_changes"
1004+
)
1005+
snapshot = _build_messages_snapshot(flow, [])
1006+
kinds = _snapshot_kinds(snapshot)
1007+
1008+
assert [kind for kind, _ in kinds] == ["text", "tool_calls"]
1009+
assert confirm_start.parent_message_id == kinds[1][1]["id"]
1010+
assert confirm_start.parent_message_id != text_message_id
1011+
1012+
9461013
def test_emit_approval_request_keeps_protocol_fields_when_tool_arguments_use_reserved_names() -> None:
9471014
"""Reserved protocol fields remain controls while editedArgs carries colliding tool arguments."""
9481015
flow = FlowState(message_id="msg-1")
@@ -1043,6 +1110,14 @@ async def test_predictive_confirmation_run_finished_interrupt_links_tool_call():
10431110
"arguments": {"content": "Draft"},
10441111
}
10451112

1113+
confirm_start = next(
1114+
event for event in events if isinstance(event, ToolCallStartEvent) and event.tool_call_name == "confirm_changes"
1115+
)
1116+
snapshots = [event for event in events if isinstance(event, MessagesSnapshotEvent)]
1117+
assert snapshots
1118+
snapshot_tool_message = next(message for message in snapshots[-1].messages if getattr(message, "tool_calls", None))
1119+
assert confirm_start.parent_message_id == snapshot_tool_message.id
1120+
10461121

10471122
def test_resume_to_tool_messages_from_interrupts_payload():
10481123
"""Resume payload interrupt responses map to tool messages."""
@@ -1782,6 +1857,8 @@ class TestEmitMcpToolCall:
17821857
def test_produces_start_and_args_events(self):
17831858
"""MCP tool call emits ToolCallStart + ToolCallArgs events."""
17841859
flow = FlowState()
1860+
_emit_text(Content.from_text("Before MCP call."), flow)
1861+
text_message_id = flow.message_id
17851862
content = Content.from_mcp_server_tool_call(
17861863
call_id="mcp_call_1",
17871864
tool_name="search",
@@ -1799,6 +1876,12 @@ def test_produces_start_and_args_events(self):
17991876
assert events[1].tool_call_id == "mcp_call_1" # type: ignore[attr-defined] # ty: ignore[unresolved-attribute]
18001877
assert "weather" in events[1].delta # type: ignore[attr-defined] # ty: ignore[unresolved-attribute]
18011878

1879+
snapshot = _build_messages_snapshot(flow, [])
1880+
kinds = _snapshot_kinds(snapshot)
1881+
assert [kind for kind, _ in kinds] == ["text", "tool_calls"]
1882+
assert events[0].parent_message_id == kinds[1][1]["id"] # type: ignore[attr-defined] # ty: ignore[unresolved-attribute]
1883+
assert events[0].parent_message_id != text_message_id # type: ignore[attr-defined] # ty: ignore[unresolved-attribute]
1884+
18021885
def test_tracks_in_flow_state(self):
18031886
"""MCP tool call is tracked in flow.pending_tool_calls and tool_calls_by_id."""
18041887
flow = FlowState()

0 commit comments

Comments
 (0)