6.5

Human in the loop: HumanInTheLoopMiddleware, batched and per call

HumanInTheLoopMiddleware pauses tool calls for review, and per_call mode is the safe choice, because batched mode lets an edit switch tools and a jumping middleware skip review.

Your agent can send email and delete files, and a person must approve each of those calls before it runs. You add one middleware with a list of tool names. The reviewer edits one call to point at a different tool, and in one mode that tool runs. In the other mode the same edit raises an error.

When you finish this section, you can pause chosen tool calls for review and answer each pause with one of four decisions. You can also choose the settings that keep the review in force.

Which calls pause

HumanInTheLoopMiddleware: the middleware that pauses an agent when the model asks for a tool in its interrupt_on map. It waits for a decision on each such call.

The interrupt_on map takes a tool name and True, which allows all four decisions, or a config with allowed_decisions. The kit gives add every decision and lookup_order two:

pythonan agent with two tools under review, batched modeFull log
    agent = create_agent(m, tools=[add, lookup_order], middleware=[HumanInTheLoopMiddleware(interrupt_on={"add": True, "lookup_order": {"allowed_decisions": ["approve", "reject"]}})], checkpointer=checkpointer)

A tool that is not in the map runs with no pause. The middleware pauses with interrupt, so the agent needs a checkpointer, as section 6.4 showed. The human-in-the-loop page names AsyncPostgresSaver for production.

The four decisions

Decision: the answer to one paused tool call. Its type is approve, edit, reject, or respond.

DecisionThe reviewer sendsDoes the tool runThe ToolMessage the model gets
approve{"type": "approve"}yes, with the arguments of the modelthe tool result, status success
editedited_action with a name and argsyes, with the edited argumentsa notice, then the tool result
rejectan optional messagenothe reason, status error
responda messagenothe message, status success

respond is for a tool whose real answer comes from the person. The model reads its message as a successful result. The docs say not to use respond to refuse a tool with side effects. The kit shows why: the model cannot tell the answer from a tool result. Use reject to refuse.

Batched mode

Batched mode: the default interrupt_mode. One interrupt holds every paused call of one model message, and one resume answers all of them in order.

The kit asked Qwen3 4B to call add and lookup_order in one reply, and it did. The run paused with one interrupt. Its value lists the calls and the decisions that each one allows:

jsonone interrupt for two callsFull log
interrupts:
[
  {
    "value": {
      "action_requests": [
        {
          "name": "add",
          "args": {
            "a": 2,
            "b": 3
          },
…
        {
          "name": "lookup_order",
…
      "review_configs": [
        {
          "action_name": "add",
          "allowed_decisions": [
            "approve",
            "edit",
            "reject",
            "respond"
          ]
        },
        {
          "action_name": "lookup_order",
          "allowed_decisions": [
            "approve",
            "reject"
          ]
        }
      ]
The descriptions and the arguments of lookup_order are cut.

While the run waits, next is HumanInTheLoopMiddleware.after_model. The resume sends a list of decisions, one for each call, in the order of action_requests. The kit edited add to 20 and 30, and rejected lookup_order:

pythonthe resume for two calls in batched modeFull log
    decisions = []
    for request in gated(result):
        if request["name"] == "add":
            decisions.append({"type": "edit", "edited_action": {"name": "add", "args": {"a": 20, "b": 30}}})
        else:
            decisions.append({"type": "reject", "message": "Do not look up orders."})
    result = agent.invoke(Command(resume={"decisions": decisions}), cfg, version="v2")
The kit builds the list from the interrupt, so it holds one decision for each call that the model made.

The model got two ToolMessage objects. The rejected call came first. The edited call ran with the new arguments, and its result starts with a notice that tells the model what ran:

jsonthe two ToolMessages after the resumeFull log
    "type": "ToolMessage",
    "content": "User rejected the tool call for `lookup_order` with reason: Do not look up orders.",
…
    "tool_call_id": "<uuid-3>",
    "status": "error"
…
    "type": "ToolMessage",
    "content": "Note: a human reviewer replaced this tool call before it ran. The call recorded in your message is the one you produced, not the one that executed. This was intentional and authorized. Do not re-issue your original call. Executed instead: add with arguments {\"a\": 20, \"b\": 30}.\n\nTool response:\n50",
…
    "tool_call_id": "<uuid-2>",
    "status": "success"
The names and the ids are cut.

The model then answered The result of the addition is 50.. The AIMessage in the state still holds the original call with 2 and 3. A list with one decision for two calls raised ValueError: Number of human decisions (1) does not match number of hanging tool calls (2)., and nothing ran.

Per-call mode

Per-call mode: interrupt_mode="per_call". Each paused call gets its own interrupt with a response_schema, and a resume answers any of them by interrupt id.

pythonan agent in per-call modeFull log
    agent = create_agent(m, tools=[add], middleware=[HumanInTheLoopMiddleware(interrupt_on={"add": True}, interrupt_mode="per_call")], checkpointer=InMemorySaver())

The model asked for add twice in one reply, for 2 and 3 and for 4 and 5. The run paused with two interrupts, and next was ["tools", "tools"]. Each interrupt names one call:

jsonthe interrupt for the first callFull log
interrupt for add(2, 3):
{
  "id": "<hex-1>",
  "value": {
    "type": "tool_approval",
    "tool_call_id": "<uuid-1>",
    "name": "add",
    "args": {
      "a": 2,
      "b": 3
    },
The description is cut.

The response_schema of each interrupt allows the four decisions. In its EditedAction, the tool name is a constant, so an edit cannot name a different tool:

jsonthe edited action in the response schemaFull log
    "EditedAction": {
      "properties": {
        "name": {
          "const": "add",
          "title": "Name",
          "type": "string"
        },
One definition from the schema of the first interrupt.

The kit resumed with a map from each interrupt id to its decision: approve the first call, reject the second. The first add returned 5, and the second got the reason with status error. The model did not report the 5. It answered I see that the tool call was rejected. and offered to try again. An answer that the schema rejects raises, and the run keeps waiting. The kit allowed only approve on one tool and sent reject:

outputa decision outside the allowed decisionsFull log
raised pydantic_core._pydantic_core.ValidationError: 1 validation error for ApproveDecision
type
  Input should be 'approve' [type=literal_error, input_value='reject', input_type=str]
The help line of pydantic is cut.

After the error, next was still ["tools"]. Per-call mode needs langchain 1.4.6 or later. The docs suggest it for new agents and plan to make it the default in the next major release. Figure 6.7 sets the two modes side by side.

Fig. 6.7batched mode and per-call modecomparison
Batched mode and per-call mode A table of four rows and two columns, batched mode on the left and per-call mode on the right. The pause: one interrupt with action requests for all calls, against one interrupt per call of type tool_approval with a schema. The resume: a list of decisions in the order of the calls, against a map of interrupt id to decision checked by response_schema. An edit to another tool: in batched case B3 delete_file ran in 3 of 3 runs, and in per-call case P3 a ValidationError meant nothing ran. A middleware that jumps to tools: in batched cases J1 to J3 the tool ran anyway, and in per-call cases J4 and J5 the review held. BATCHED PER CALL the pause one interrupt action_requests for all calls one interrupt per call type tool_approval, a schema the resume a list of decisions in the order of the calls a map of id to decision checked by response_schema an edit to another tool delete_file ran B3, 3 of 3 runs ValidationError P3, nothing ran, 3 of 3 a middleware jumps to tools the tool ran anyway J1, J2, J3, 3 of 3 runs the review held J4, J5, nothing ran Rows 1 and 2 are from the capture kit. Rows 3 and 4 are lab runs on the x86 server guest.
Batched mode answers one list for all calls of a message, and per-call mode answers each call by its interrupt id against a schema. Read each row across the two columns. The rows are the pause, the resume, an edit to another tool, and a middleware that jumps to tools. Rose cells are where a review did not hold.

What the lab found

We measured the middleware on the x86 server guest in 25 model cases, 3 runs of each. The model was Qwen3 4B on Ollama (temperature 0, seed 42). The graph cases G1 and G2 have no model and come from the Mac. The tools were send_email and delete_file, both under review. Raw runs

Each start and each resume ran in a new process against SqliteSaver, so every resume was a restart. All 3 runs of each case gave the same tool runs. Figure 6.8 shows each run.

Fig. 6.8tool runs in each approval casechart
Tool runs in each approval case A dot chart of tool runs for 22 approval cases with Qwen3 4B on the x86 server guest, 3 runs each, with a short line at the number of tool runs the decisions allowed. Batched cases B1 to B9 and per-call cases P1 to P8, J4, and J5 sit on their lines in all runs. The batched cases J1, J2, and J3, with a middleware that jumps to tools, each ran 1 tool in every run without an approval, and are drawn in rose. 0 1 2 tools run in one case B1 B2 B3 B4 B5 B6 B7 B8 B9 J1 J2 J3 batched P1 P2 P3 P4 P5 P6 P7 P8 J4 J5 per call tools matched the decisions a tool ran with no approval Each dot is one run on the x86 server guest. The grey line is the allowed count.
Each case gave the same tool runs in 3 of 3 runs, and only batched cases ran a tool that no approval allowed. Read one column for each of the 22 middleware cases. The graph and strict resume cases G1 to G3, S1, and S2 are not drawn. Each dot is one run on the x86 server guest. A dot on the line is a run whose tools matched the decisions, and a rose dot ran a tool that no approval allowed.

The grey line of the figure is the number of tool runs that the reviewer allowed in each case. The figure code holds these counts as constants. They come from the decisions in the table below and from the case scripts in capture/lab/T07-approvals-x86/. The cases have short codes. B is batched, P is per call, J adds a middleware that jumps to tools, and G is a plain graph.

CaseWhat the reviewer didResult, in 3 of 3 runs
B2, P2edit the arguments of send_emailonly the edited call ran
B3edit send_email into a call of delete_filedelete_file ran
P3the same edit in per-call modeValidationError, nothing ran
B4, P4rejectnothing ran, status error
B5, P5respondnothing ran, status success
P7answer two calls one at a timeeach call ran once
P8a plain value for two waiting callsRuntimeError, nothing ran
J1, J3batched, the jumping middleware after the review middleware in the listsend_email ran at the start, before any decision
J2batched, the jumping middleware first, rejectsend_email ran, and the state held two ToolMessages for one call
J4, J5per call, either order, rejectnothing ran
G1, G2two parallel interrupts in a graph and a subgraph, answered one at a timeeach branch ran its side effect once

In 10 two-action requests, Qwen3 4B and Qwen3 8B each made two or more calls in 9. So a batched review of several calls is the common case.

The B3 row settles conflict D102. One batched example in the docs edits a call to a new tool name, and the per-call text keeps the name. The changelog for 1.4.6 says that an edit cannot switch tools. At the pin, batched mode still allows the switch, and per-call mode refuses it.

The J rows reproduce issue langchain#40492 in batched mode. The jumping middleware returns jump_to="tools" from after_model. after_model hooks run in the reverse order of the middleware list. So in J1 and J3 its hook ran before the review hook and skipped it.

In J2 the review ran, the call was rejected, and the jump still ran the tool. The two ToolMessages for one call in J2 break the rule of section 3.4: one answer for each tool call. Per-call mode puts its pause in the tool call itself, and the jump did not skip it.

Two older issues did not reproduce. Issue langchain#33787 said that an edit could still run the original call. In B2 and P2 only the edited call ran. Issue langgraph#9106 said that a resume ran a finished parallel branch again. In G1 and G2 the finished branch did not run again. The branch still waiting ran its node up to interrupt on each resume, which is the rule of section 6.4.

The safe configuration

These settings kept every review in force in the lab runs:

  1. Set interrupt_mode="per_call", so an edit stays on its tool and a jump to tools does not skip the review.
  2. Use a checkpointer that survives a restart, such as SqliteSaver or PostgresSaver.
  3. Allow only the decisions you need for each tool. Leave out respond and edit for a tool with side effects, and refuse with reject.
  4. Answer each interrupt by its id, and check next with get_state before you resume.
  5. Put no middleware that jumps to tools in an agent with review, unless you test it in your mode.
  6. List HumanInTheLoopMiddleware before tool retry and error middleware, as the docs say.

Agent Chat UI answers batched approvals only, and a typed message closes a pending approval as a success. See the chat UI section.

The docs also warn about one invalid answer among several sent together. The tools of the valid answers can run while their interrupts still look pending, and a second answer runs them twice. So answer one interrupt at a time, and make the side effects idempotent. After a failed combined resume, check what the tools did before you send the answer again. The lab did not run that case, or any case with PostgresSaver. Both come in the next edition, with the other open items of section 8.8.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11