LangGraph's interrupt + useStream: The Minimal Human-in-the-Loop Loop
LangGraph HITL in Practice: The Minimal Loop from interrupt to useStream
Human-in-the-loop (HITL) is an unavoidable part of deploying agents: the model can run on its own, but key actions need a human nod. LangGraph packages this as an interrupt + useStream combination—the backend throws the question, the frontend answers, and the flow resumes automatically. Below, using a "pre-search approval" example, we clarify how to use it.
1. Backend: Throw the question with interrupt
queries = [state["messages"][-1].tool_calls.get("query") for call in calls]
approved = interrupt({
"question": "The model wants to search the following content, allow?",
"queries": queries,
})
Three things are worth noting:
interruptaccepts any serializable dict; it is passed to the frontend unchanged. Here we passquestionandqueriesfields, so the frontend can combine a full prompt.interrupt's return value is exactly the value the frontend sends back withrespond. When the user clicks "confirm,"approvedbecomestrue; "cancel" becomesfalse. The backend uses this value to decide which branch to take.- The placement of the interrupt is critical—it should be placed in the window between "the model has decided to call a tool" and "the tool hasn't executed yet." This way the human approves the "intent" rather than the "already-occurred result," making the interception meaningful.
2. Frontend: Catch the problem with useStream and send it back
const stream = useStream({ assistantId, apiUrl: () => apiUrl.value })
const pendingInterrupt = computed(() => stream.interrupt.value?.value ?? null)
watch(pendingInterrupt, (val) => {
let res = confirm(val.question + val.queries.join(","))
stream.respond(res)
})
Let's break it down:
stream.interruptis a reactive reference. As soon as the backend throws an interrupt, it updates and carries the payload (i.e.,questionandqueries).watchmonitors it and pops a dialog when a new interrupt arrives. Hereconfirmis the simplest interaction;val.question + val.queries.join(",")constructs the prompt text.stream.respond(res)sends the user's answer back to the backend. This value becomes the return value ofinterrupt(...), letting the backend node continue from the pause point.
3. The complete timing of this loop
- The model decides to call the search tool and generates
tool_calls. - The node executes
interrupt(...); LangGraph pauses the current graph and pushes the payload to the frontend. - The frontend's
useStreamreceives the interrupt;watchtriggers theconfirmdialog. - The user clicks confirm/cancel;
stream.respond(true/false)sends it back. - The backend's
interruptreturns this value, assigns it toapproved, and the node continues.
4. Usage summary
| Role | What to do | Key APIs |
|---|---|---|
| Backend | Throw the question where human decision is needed | interrupt(payload), return value is the user's reply |
| Frontend | Listen for interrupts, display, send back | stream.interrupt, stream.respond(value) |
| Connection | The payload and the backend return value are the same value | The fields between front and back must be agreed upon |
This is the minimal viable loop for HITL: backend interrupt throws the question, frontend useStream catches it, respond returns the answer, and the graph automatically resumes. Once you master this pattern, you can replace confirm with an approval form and replace boolean values with structured objects, expanding interaction granularity as business needs dictate.
Note: The function where the backend interrupt breakpoint resides will re-execute after user confirmation, so it runs twice.
Top 2 of 6 from juejin.cn, machine-translated. The original thread is authoritative.
Bro, do you have the source code? Can I reference your local source code?
https://gitee.com/liyefeng123/projects. The blue one is a combo of frontend and backend. The red one is a combo of frontend and backend. Both projects are already deployed and live, but the addresses aren't convenient to make public. If you have questions, DM me.
Also there's an .env file, roughly like this, can't upload it.
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.