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

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 decisions that correspond to each action request in order.

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}

Complete Resume Example

The decisions list 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)

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