Native AG-UI interrupts | RunFinished.outcome.interrupt + resume[]

[DoronYitz]

I'm using @tanstack/ai / @tanstack/ai-client on the frontend, with a backend built on LangGraph / LangChain that speaks the AG-UI protocol.

First off — I can see that TanStack AI already supports tool approvals via the CUSTOM approval-requested event (needsApproval → approval-requested → addToolApprovalResponse), and that flow works well. My question is specifically about interop with the native AG-UI interrupt contract, which appears to be a different mechanism.

What I'm trying to do

Support the AG-UI human-in-the-loop interrupt flow from the spec: https://docs.ag-ui.com/concepts/interrupts

The spec models HITL as an interrupt-aware run lifecycle:

• The agent pauses by ending a run with RUN_FINISHED carrying an interrupt outcome:

{
  "type": "RUN_FINISHED",
  "threadId": "thread-1",
  "runId": "run-1",
  "outcome": {
    "type": "interrupt",
    "interrupts": [
      {
        "id": "int-abc",
        "reason": "tool_call",
        "toolCallId": "tc-001",
        "message": "Send email to a@b.com?",
        "responseSchema": {
          "type": "object",
          "properties": { "approved": { "type": "boolean" } },
          "required": ["approved"]
        }
      }
    ]
  }
}

• The client resumes by sending the next RunAgentInput on the same thread with a top-level resume array:

{
  "threadId": "thread-1",
  "runId": "run-2",
  "resume": [
    { "interruptId": "int-abc", "status": "resolved", "payload": { "approved": true } }
  ]
  ....
}

• On resume, the agent emits TOOL_CALL_RESULT against the original toolCallId (it does not re-emit TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END), then RUN_FINISHED with outcome: { type: "success" }.

LangGraph natively supports this (it accepts RunAgentInput.resume[] and can emit RunFinished.outcome = { type: "interrupt" }).

What I found looking at the client internals

1. Approval decision isn't serialized to the wire. The approval path is CUSTOM-event based (approval-requested) and stores the decision on the message part (state: "approval-responded", approval.approved) — but uiMessagesToWire doesn't serialize approval / approved. So on the resume run, a non-TanStack backend never receives the approve/deny decision.
2. RUN_FINISHED.outcome is ignored. handleRunFinishedEvent only reads chunk.finishReason, so the client never surfaces outcome.interrupt.
3. No top-level resume field. buildRunAgentInputBody produces a fixed shape (threadId, runId, state, messages, tools, context, forwardedProps, data), and forwardedProps / body / data all land nested under forwardedProps — not at the request root where the spec puts resume.

My understanding is that TanStack's approval flow is designed around the TanStack engine (which recovers the decision from the parts model, e.g. extractClientStateFromOriginalMessages) rather than the AG-UI interrupt wire contract. That works great TanStack-engine ↔ TanStack-client, but doesn't interop with an AG-UI agent that expects outcome.interrupt + resume[].

Questions

1. Is native AG-UI interrupt support (RUN_FINISHED.outcome.interrupt inbound, top-level resume[] outbound) supported today, or on the roadmap? Is the intended approach to keep using approval-requested and have the backend adapt, or to speak the interrupt contract directly?
2. If native interrupts aren't supported yet, is a custom connection adapter the intended extension point — i.e. reading outcome.interrupt from the stream and building the request body myself to inject a top-level resume[]? Is there a cleaner/supported hook I'm missing?
3. Is there a supported way to trigger a resume run with no new user message (a "continue" that re-POSTs the thread), other than piggybacking on addToolResult / addToolApprovalResponse auto-continuation?
4. Any plan to make RUN_FINISHED.outcome (success / interrupt) first-class in the client state, so UIs can render interrupt prompts from message / responseSchema / reason?

Any guidance on the recommended pattern for AG-UI interrupt interop would be much appreciated.

[AlemTuzlak]

This will land together with the upcoming persistence PR.

[ofekron]

Native interrupt support should make the interrupt a durable thread-level object, not merely another message part. The approval UI is a projection of that object; it should not be the source of truth.

I would preserve these invariants across adapters:

• interruptId is stable and unique within the thread;
• RUN_FINISHED with an interrupt persists the full reason/schema/toolCallId before the run is considered settled;
• resume[] is idempotent, so reconnect/retry cannot apply the same decision twice;
• resolving an interrupt starts a new run without requiring a synthetic user message;
• TOOL_CALL_RESULT remains linked to the original toolCallId, while the new runId identifies the continuation attempt;
• unresolved interrupts survive reload and are returned by the normal persistence snapshot.

A custom connection adapter can bridge this temporarily, but only if the client state model exposes interrupt outcomes first-class. Otherwise every adapter has to maintain a shadow state machine and recovery becomes ambiguous.

We use the same ownership split in Better Agent for native Claude, Codex, and Gemini approvals: the backend persists pending decisions and continuation state, while clients render and acknowledge them. I maintain it; the project is source-available and free for non-commercial use, while commercial use requires separate permission: https://github.com/ofekron/better-agent

AI-assistance disclosure: this comment was drafted by Codex under the maintainer’s authorization and reviewed in Better Agent.