Middleware that enables human oversight and intervention in agent workflows.

HumanInTheLoop (HITL) allows pausing agent execution before executing sensitive or critical tool operations, providing humans with the ability to approve, edit, or reject tool calls.

Configuration

The middleware is configured with an interrupt_on map that specifies which tools should trigger human approval:

# Simple boolean configuration
interrupt_on = %{
  "write_file" => true,           # Enable with default decisions
  "delete_file" => true,
  "read_file" => false            # No interruption
}

# Advanced configuration with custom decisions
interrupt_on = %{
  "write_file" => %{
    allowed_decisions: [:approve, :edit, :reject]
  },
  "delete_file" => %{
    allowed_decisions: [:approve, :reject]  # No edit option
  }
}

Decision Types

• :approve - Execute the tool with original arguments
• :edit - Execute the tool with modified arguments
• :reject - Skip tool execution entirely

Recovery

An approved tool can be interrupted by the agent process stopping (a crash, a deploy, a lost node) after it has started and before its result is recorded. :recovery says what the next boot does about it:

• :report_unknown (default) - Record a result telling the model the call was started and its outcome is unknown, so the model can check before trying again. The call is never re-run on its own.
• :reexecute - Run the approved calls again, with the same decisions. Only for tools that are safe to repeat, for example because they are idempotent by tool_call_id (available as context.tool_call_id).

A batch is re-run only when every call in it that was started is :reexecute. A tool call that does not need approval but was in the same batch counts as :report_unknown.

interrupt_on = %{
  "set_thermostat" => %{allowed_decisions: [:approve, :reject], recovery: :reexecute},
  "send_payment" => true
}

Calls that cannot run

A human is only asked about calls that would actually run. Before interrupting, each gated call's arguments are parsed by its own tool, with the context the tool would run with: its :parse_args parser, or the required-parameter check when it has none (see LangChain.Function). A call naming a tool the agent does not have is refused the same way.

A refused call is not put to a human. It is answered with the tool's message as an error result, the same answer it would get if it ran, so the model can correct it. When other calls still need approval, the refused ones are held in the interrupt data under :pre_decided and answered when the batch is resumed. They are never executed, even if their arguments would parse by then. When no call needs approval, the batch runs at once.

The parser runs again when an approved call executes, and only that run's result reaches the tool body. An approval can wait a long time, and data can change in between. A parser therefore runs more than once for one call, and must only read, never write.

A tool that wants a no-op call ("nothing would change") kept away from the human refuses it from its parser.

Durability

An interrupt survives the agent process. When approval is needed, the conversation gets a tool message holding one placeholder result per pending tool call, each carrying this interrupt's data, and it is persisted with the state. A later boot rebuilds the interrupt from it and comes up :interrupted.

When approval is given, the placeholders are marked as running, with the decisions and the recovery policy, and that is persisted before any tool runs. If the agent stops before the run's result is persisted, the next boot applies the recovery policy instead of asking again or dropping the calls.

Usage

# Create agent with HITL middleware
{:ok, agent} = Agent.new(
  model: model,
  interrupt_on: %{
    "write_file" => true,
    "delete_file" => true
  }
)

# Execute - will return interrupt if tool needs approval
state = State.new!(%{messages: [...]})
result = Agent.execute(agent, state)

case result do
  {:ok, state} ->
    # Normal completion
    handle_response(state)

  {:interrupt, state, interrupt_data} ->
    # Human approval needed
    decisions = get_human_decisions(interrupt_data)
    {:ok, final_state} = Agent.resume(agent, state, decisions)
end

Interrupt Structure

When a tool requires approval, execution returns an interrupt tuple with detailed information about the tools requiring approval.

Structure

{:interrupt, state, %{
  action_requests: [action_request, ...],
  review_configs: %{tool_name => config, ...}
}}

Action Requests

Each action request contains complete information about the tool call:

%{
  tool_call_id: "call_123",      # Unique identifier for this tool call
  tool_name: "write_file",       # Name of the tool being called
  arguments: %{...}              # Arguments that would be passed to the tool
}

Review Configs

A map of tool names to their approval configuration. More efficient than the Python library's array-based approach, providing O(1) lookup:

%{
  "write_file" => %{
    allowed_decisions: [:approve, :edit, :reject]
  },
  "delete_file" => %{
    allowed_decisions: [:approve, :reject]  # Edit not allowed
  }
}

Complete Example

{:interrupt, state, %{
  action_requests: [
    %{
      tool_call_id: "call_123",
      tool_name: "write_file",
      arguments: %{"path" => "file.txt", "content" => "data"}
    },
    %{
      tool_call_id: "call_456",
      tool_name: "delete_file",
      arguments: %{"path" => "old.txt"}
    }
  ],
  review_configs: %{
    "write_file" => %{allowed_decisions: [:approve, :edit, :reject]},
    "delete_file" => %{allowed_decisions: [:approve, :reject]}
  }
}}

Resume Structure

Resume execution by providing one decision per action request. A decision answers an action request either by naming its :tool_call_id, or by position when no decision names one (see Sagents.AgentUtils.pair_decisions/2). Naming the id is the safer form for a UI that lets the user decide tools in any order: Sagents.AgentUtils.advance_hitl_decisions/3 builds decisions this way.

Decision Types

• :approve - Execute the tool with its original arguments
• :edit - Execute the tool with modified arguments (requires :arguments field)
• :reject - Skip tool execution, provide rejection message to agent

Decision Format

Each decision is a map with a required :type field:

# Approve decision
%{type: :approve}

# Edit decision (must include :arguments with the modified parameters)
%{type: :edit, arguments: %{"path" => "modified.txt", "content" => "new data"}}

# Reject decision
%{type: :reject}

Any decision may also carry the :tool_call_id of the action request it answers. Either every decision carries one or none does.

Complete Resume Example

Positional decisions must match the order and count of action_requests:

# Given interrupt with 3 action requests
{:interrupt, state, %{action_requests: [req1, req2, req3], ...}}

# Provide corresponding decisions
decisions = [
  %{type: :approve},                                    # Approve req1
  %{type: :edit, arguments: %{"path" => "other.txt"}}, # Edit req2's arguments
  %{type: :reject}                                      # Reject req3
]

# Resume execution
{:ok, final_state} = Agent.resume(agent, state, decisions)

Decisions keyed by :tool_call_id may come in any order:

decisions = [
  %{type: :reject, tool_call_id: req3.tool_call_id},
  %{type: :approve, tool_call_id: req1.tool_call_id},
  %{type: :edit, tool_call_id: req2.tool_call_id, arguments: %{"path" => "other.txt"}}
]

Position in Middleware Stack

HITL must be the last middleware in the stack. This is required because during handle_resume, HITL executes ALL tool calls from the interrupted assistant message (auto-approving non-HITL tools). If an auto-approved tool produces its own interrupt (e.g., ask_user), HITL detects this and hands off via {:cont} so the owning middleware can claim it. Since the handle_resume middleware cycle is single-pass, only middleware that comes AFTER HITL in the stack will see the handoff. Placing interrupt-producing middleware before HITL ensures they get a chance to claim interrupts discovered during HITL's tool execution.

HumanInTheLoop.maybe_append/2 enforces this by always appending to the end of the middleware list.

Default stack position:

1. TodoList
2. FileSystem
3. SubAgent
4. Summarization
5. PatchToolCalls
6. AskUserQuestion (or other interrupt-producing middleware)
7. HumanInTheLoop ← Always last