跪拜 Guibai
← Back to the summary

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:

  1. interrupt accepts any serializable dict; it is passed to the frontend unchanged. Here we pass question and queries fields, so the frontend can combine a full prompt.
  2. interrupt's return value is exactly the value the frontend sends back with respond. When the user clicks "confirm," approved becomes true; "cancel" becomes false. The backend uses this value to decide which branch to take.
  3. 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:

3. The complete timing of this loop

  1. The model decides to call the search tool and generates tool_calls.
  2. The node executes interrupt(...); LangGraph pauses the current graph and pushes the payload to the frontend.
  3. The frontend's useStream receives the interrupt; watch triggers the confirm dialog.
  4. The user clicks confirm/cancel; stream.respond(true/false) sends it back.
  5. The backend's interrupt returns this value, assigns it to approved, 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.

Comments

Top 2 of 6 from juejin.cn, machine-translated. The original thread is authoritative.

kongzhi

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.

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.