Python: [Bug]: AG-UI resume duplicates the interrupted turn when the client replays its transcript #8140

summary

on an AG-UI resume request, agent-framework-ag-ui prepends the stored thread snapshot to RunAgentInput.messages and persists the concatenation without de-duplication. a client that replays its transcript on resume, which is what the reference AG-UI client does, therefore has the interrupted turn written into the stored snapshot twice. after a refresh the duplicated assistant tool-call has no matching tool result, so an approval UI reopens for a call that already ran.

MAF already has both defences needed here; the resume path just does not use them.

why this is a host-side issue

the AG-UI interrupt spec does not define what messages carries on a run that also carries resume. its contract rules (docs/concepts/interrupts.mdx) constrain the thread id, interrupt coverage, idempotency, payload validation, and expiry, and none of them mentions messages. so both readings are conformant, and clients differ.

the reference TypeScript client sends the full transcript. AbstractAgent.prepareRunAgentInput (sdks/typescript/packages/client/src/agent/agent.ts, read at @ag-ui/[email protected] = 9f393021e) spreads resume on top of an input whose messages is this.messages with only role !== "activity" filtered out. there is no resume-aware trimming anywhere on that path. so HttpAgent pointed at a MAF endpoint reproduces this with no third-party code involved.

for contrast, the other resume-aware AG-UI integrations at that ref (langgraph py+ts, mastra, crew-ai, aws-strands py+ts) all short-circuit before reading messages on a resume, and the stateful ones de-duplicate by message id, with comments naming full-transcript replay as the expected steady state. MAF's messages: [] expectation is reasonable, but it is currently enforced by nothing.

mechanism

all line numbers at 05911fea70b5cf1b0728b186faa8d36883d086c9, package agent-framework-ag-ui.

1. _snapshot_session.py:134-142 concatenates without filtering:

def resume_seeded_messages(self, incoming: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """Prepend copies of stored thread history to a resume request's messages.

    Resume requests carry only the synthesized interrupt response; seeding
    with stored history keeps the persisted thread from being truncated.
    """
    if self._stored is None:
        return incoming
    return [copy.deepcopy(message) for message in self._stored.messages] + incoming

the docstring states the assumption the concatenation depends on, and nothing checks it.

2. _agent_run.py:2481-2499 routes resume around the reconciler every other path uses:

if stored_snapshot is not None:
    if resume_payload is not None and stored_pending_approval_interrupt_ids:
        seeded_resume_from_snapshot = True

        if not config.use_service_session:
            raw_messages = snapshot_session.resume_seeded_messages(raw_messages)
        ...
    elif not config.use_service_session:
        raw_messages = _reconstruct_messages_from_thread_snapshot(
            stored_messages=stored_snapshot.messages,
            incoming_messages=raw_messages,
            stored_interrupt=stored_snapshot.interrupt,
        )

the elif branch is exactly the "client re-sent history" defence: _reconstruct_messages_from_thread_snapshot (_run_common.py) finds the overlap between stored and incoming, trims the matched prefix, and filters the untrusted suffix. the resume branch above it never reaches that. note the service-session resume path does delegate to the same reconstructor via _split_service_session_input, so the gap is confined to not config.use_service_session resumes (and the equivalent workflow resume in _workflow.py).

3. _message_adapters.py:576-581 de-duplicates the provider-facing list and then builds the snapshot from the raw argument, bypassing it:

provider_messages = agui_messages_to_agent_framework(messages)
if sanitize_tool_history:
    provider_messages = _sanitize_tool_history(provider_messages, protected_tool_call_ids=protected_tool_call_ids)
provider_messages = _deduplicate_messages(provider_messages)
snapshot_messages = agui_messages_to_snapshot_format(messages)
return provider_messages, snapshot_messages

_deduplicate_messages (:292) keys tool results by (role, call_id), assistant tool-calls by their sorted call-id tuple, and everything else by message_id. agui_messages_to_snapshot_format (:1227) is a strict 1:1 per-message normalizer with no keying at all.

that split is why the symptom is invisible during the run and only appears after a reload: the model call sees a clean list, while the persisted snapshot and the outbound MESSAGES_SNAPSHOT keep the duplicate.

reproduction

1. serve an agent through agent-framework-ag-ui with snapshot persistence enabled and a tool that requires approval.
2. drive it with a client that replays its transcript on resume. plain @ag-ui/client HttpAgent does this by default; no configuration needed.
3. run a turn that interrupts on the tool call, then resume with resume: [{ interruptId, status: "resolved", payload: { approved: true } }] and the transcript still in messages.
4. the tool runs and the turn completes normally.
5. hydrate the thread (threadId, messages: [], no resume).

expected: one user turn and one assistant tool-call, resolved.

actual: the user turn and the assistant tool-call appear twice; the duplicate assistant tool-call has no tool result, and interrupt is null. a client rendering approval state from the snapshot reopens the gate for a call that already executed.

suggested fix

route the resume branch through the reconciler the sibling branch already uses, so a replayed transcript is detected and trimmed rather than assumed absent. _reconstruct_messages_from_thread_snapshot already computes the stored-vs-incoming overlap and accepts an id match, which is precisely this case.

failing that, applying _deduplicate_messages to snapshot_messages as well as provider_messages in _message_adapters.py would keep the duplicate out of persistence, though it leaves the model-facing and snapshot lists derived by two different rules.

either way, since the spec does not mandate messages: [] on resume, treating it as a precondition rather than a hint means a conformant client can corrupt the stored thread.

secondary observation, not verified by running it

_agent_run.py:3239 seeds again at save time when resume_payload is not None and not seeded_resume_from_snapshot and snapshot_seed_messages is None. a resume arriving with stored_pending_approval_interrupt_ids already empty takes the elif at :2494, so latest_messages_snapshot would already contain stored history, and this second seeding would prepend it again. that reads as a self-inflicted duplication independent of what the client sends, but it is a code reading only.

refs read

• microsoft/agent-framework at 05911fea70b5cf1b0728b186faa8d36883d086c9, python/packages/ag-ui (agent-framework-ag-ui 1.2.2)
• ag-ui-protocol/ag-ui at 9f393021ecbd6bcc62dc4b1ad5a6ac4b797565f4 (tags @ag-ui/[email protected] and @ag-ui/[email protected])

downstream report that surfaced this: assistant-ui/assistant-ui#7011.