跪拜 Guibai
← All articles
Artificial Intelligence

LangGraph's interrupt + useStream: The Minimal Human-in-the-Loop Loop

By 锋行天下 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

This removes the need to hand-roll approval workflows in agent orchestration, but the interrupt function re-runs after confirmation, so any side effects must be idempotent or you'll get duplicate work.

Summary

LangGraph's human-in-the-loop pattern splits responsibility across the stack. The backend calls interrupt(...) at a point where the model has decided to call a tool but hasn't executed it yet. That call accepts any serializable dict, sends it to the frontend, and pauses the graph. Its return value is whatever the frontend later sends back. The frontend uses useStream to hook into the stream, listens to stream.interrupt as a reactive ref, then calls stream.respond with the user's answer. The backend gets that value from interrupt and continues from the paused point.

The full sequence: model generates tool_calls, the node hits interrupt, the payload arrives on the frontend, a watch triggers a confirm dialog, stream.respond sends true/false, and the backend assigns that to approved. One caveat: the function containing the interrupt executes twice—once to pause, once after the user confirms—so any side effects before or after must be idempotent. The example uses a simple confirm, but the payload dict is structured, so you can swap in an approval form or any rich UI without changing the backend contract.

Takeaways
— interrupt accepts any serializable dict and passes it to the frontend unchanged.
— The return value of interrupt is exactly the value passed to stream.respond.
— Place interrupt between the model's tool-call decision and tool execution to approve intent, not results.
— useStream exposes stream.interrupt as a reactive reference that updates when the backend pauses.
— A watch on pendingInterrupt triggers the UI dialog; stream.respond sends the answer back.
— The node function executes twice: once to pause and once after the user confirms.
Conclusions

Because interrupt re-runs the enclosing function, developers must design that code to be idempotent or accept duplicate side effects.

The payload dict carries structured data to the frontend, so you can replace the simple confirm with any approval UI without touching the backend contract.

LangGraph treats human approval as an ordinary pause, not a special case, which keeps the graph state machine uniform.

Concepts & terms
HITL
Human-in-the-loop: a design that inserts human approval or input into an automated process, here used for agent tool-call permission.
interrupt
A LangGraph API that pauses graph execution at a point and sends a serializable payload to the frontend; its return value is the user's response.
useStream
A React hook from LangGraph's frontend library that exposes the graph stream, including stream.interrupt and stream.respond for handling interruptions.
From the discussion

The thread digs into LangGraph's interrupt semantics: resuming a paused graph re-runs the whole node from the beginning rather than continuing from the interrupt call, so any side effects before interrupt repeat. A commenter details duplicate audit records and how they moved writes after interrupt or added idempotency keys, plus notes that interrupt without a checkpointer throws rather than pauses, and changing the session id loses the state. A follow-up confirms the re-execution behavior with a simple print example and stresses designing code order accordingly.

— Resuming from an interrupt re-executes the entire node from the top, not just the code after the interrupt line, so side effects before interrupt fire twice.
— To prevent duplicate writes, either move database operations after interrupt or add an idempotency key scoped to session and step.
— Interrupt requires a checkpointer; without one it throws instead of pausing, and swapping session id on resume starts a fresh empty state, breaking the flow.
— Interrupt must sit inside a node and outside any try/catch, because a swallowed exception leaves the graph permanently stuck.
— The author concurs and emphasizes that the order of code logic in real projects must account for the re-execution.
Featured comments
booboosui

Your phrase 'continue execution from the pause point' is the next most likely trap. When LangGraph resumes, it doesn't continue from the interrupt line; it re-executes the entire node from the start, only that interrupt call becomes a direct return of your respond value. So side effects before interrupt happen a second time: in my case, I write an audit record before approval, and after clicking approve the record becomes two. I initially thought the frontend had resend the request. The current approach is to move the database write after interrupt, or give the write a key like 'same session, same step, write only once'. The second hurdle is the checkpointer. Without a checkpointer attached to the graph, interrupt just throws, not pauses; when resuming, if you change the session id, it treats it as a new session starting from empty state, and the approval popup never comes back, with nothing in the logs. By the way, interrupt must be placed inside a node and not wrapped in try; if wrapped, the exception gets swallowed and the graph just stops there.

锋行天下

This teacher hits the extreme pain point. For example, I print 111 before interrupt and 222 after. During execution, 111 prints, then the code pauses and doesn't continue. After the user confirms, the whole function re-executes, so 111 prints again, then 222 prints. That is, code before interrupt will execute repeatedly, so in real projects you need to design the order of code logic carefully. What I said earlier wasn't detailed enough; thanks to this buddy for the supplement.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗