> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-opensw-1783454697-4d4e2b4.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Human-in-the-loop The Human-in-the-Loop (HITL) [middleware](/oss/python/langchain/middleware/built-in#human-in-the-loop) lets you add human oversight to agent tool calls. When a model proposes an action that might require review—for example, writing to a file or executing SQL—the middleware can pause execution and wait for a decision. It does this by checking each tool call against a configurable policy. If intervention is needed, the middleware issues an [interrupt](https://reference.langchain.com/python/langgraph/types/interrupt) that halts execution. The graph state is saved using LangGraph's [persistence layer](/oss/python/langgraph/persistence), so execution can pause safely and resume later. A human decision then determines what happens next: the action can be approved as-is (`approve`), modified before running (`edit`), rejected with feedback (`reject`), or responded to directly (`respond`) for "ask user" style tools. ## Interrupt decision types The [middleware](/oss/python/langchain/middleware/built-in#human-in-the-loop) defines four built-in ways a human can respond to an interrupt: | Decision Type | Description | Example Use Case | | ------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | ✅ `approve` | Execute the tool with the original arguments as proposed by the agent. | Send an email draft exactly as written | | ✏️ `edit` | Modify the tool arguments before execution. | Change the recipient before sending an email | | ❌ `reject` | Skip executing this tool call entirely and return rejection feedback to the agent. | Deny file deletion and explain why | | 💬 `respond` | Return the human's message directly as a synthetic tool result, skipping execution, for "ask user" style tools. | Answer an `"ask_user"` prompt with a direct reply | The available decision types for each tool depend on the policy you configure in `interrupt_on`. When multiple tool calls are paused at the same time, each action requires a separate decision. Decisions must be provided in the same order as the actions appear in the interrupt request. Use `reject` when the human is denying the requested action. Use `respond` only when the human is acting as the tool, such as answering an `ask_user` prompt. Do not use `respond` to deny side-effecting tools, because its message is treated as a successful tool result. When **editing** tool arguments, make changes conservatively. Significant modifications to the original arguments may cause the model to re-evaluate its approach and potentially execute the tool multiple times or take unexpected actions. ## Configuring interrupts To use HITL, add the [middleware](/oss/python/langchain/middleware/built-in#human-in-the-loop) to the agent's `middleware` list when creating the agent. You configure it with a mapping of tool actions to the decision types that are allowed for each action. The middleware will interrupt execution when a tool call matches an action in the mapping. ```python theme={null} from langchain.agents import create_agent from langchain.agents.middleware import HumanInTheLoopMiddleware # [!code highlight] from langgraph.checkpoint.memory import InMemorySaver # [!code highlight] agent = create_agent( model="gpt-5.5", tools=[write_file, execute_sql, read_data], middleware=[ HumanInTheLoopMiddleware( # [!code highlight] interrupt_on={ "write_file": True, # All decisions (approve, edit, reject, respond) allowed "execute_sql": {"allowed_decisions": ["approve", "reject"]}, # No editing allowed "read_data": False, # Safe operation, no approval needed }, # Prefix for interrupt messages - combined with tool name and args to form the full message # e.g., "Tool execution pending approval: execute_sql with query='DELETE FROM...'" # Individual tools can override this by specifying a "description" in their interrupt config description_prefix="Tool execution pending approval", ), ], # Human-in-the-loop requires checkpointing to handle interrupts. # In production, use a persistent checkpointer like AsyncPostgresSaver. checkpointer=InMemorySaver(), # [!code highlight] ) ``` You must configure a checkpointer to persist the graph state across interrupts. In production, use a persistent checkpointer like [`AsyncPostgresSaver`](https://reference.langchain.com/python/langgraph/checkpoints/#langgraph.checkpoint.postgres.aio.AsyncPostgresSaver). For testing or prototyping, use [`InMemorySaver`](https://reference.langchain.com/python/langgraph/checkpoints/#langgraph.checkpoint.memory.InMemorySaver). When invoking the agent, pass a `config` that includes the **thread ID** to associate execution with a conversation thread. See the [LangGraph interrupts documentation](/oss/python/langgraph/interrupts) for details. Mapping of tool names to approval configs. Values can be `True` (interrupt with default config), `False` (auto-approve), or an `InterruptOnConfig` object. Prefix for action request descriptions **`InterruptOnConfig` options:** List of allowed decisions: `'approve'`, `'edit'`, `'reject'`, or `'respond'` Static string or callable function for custom description Optional predicate that receives a [ToolCallRequest](https://reference.langchain.com/python/langgraph.prebuilt/tool_node/ToolCallRequest) and returns `True` to interrupt or `False` to auto-approve. Use it to gate interrupts on a call's arguments. Requires `langchain>=1.3.3`. ## Conditional interrupts By default, every tool call listed in `interrupt_on` pauses for review. To pause only some calls, add a `when` predicate to a tool's `InterruptOnConfig`. The predicate receives a `ToolCallRequest` and returns `True` to interrupt or `False` to auto-approve, so you can gate on the tool's arguments. Conditional interrupts require `langchain>=1.3.3`. ```python theme={null} from langchain.agents import create_agent from langchain.agents.middleware import HumanInTheLoopMiddleware, ToolCallRequest from langgraph.checkpoint.memory import InMemorySaver def writes_outside_workspace(request: ToolCallRequest) -> bool: """Pause writes to paths outside the workspace directory.""" path = request.tool_call["args"].get("path", "") return not path.startswith("/workspace/") def is_write_query(request: ToolCallRequest) -> bool: """Pause SQL that isn't a read-only SELECT.""" query = request.tool_call["args"].get("query", "") return not query.lstrip().upper().startswith("SELECT") agent = create_agent( model="gpt-5.5", tools=[write_file, execute_sql, read_data], middleware=[ HumanInTheLoopMiddleware( interrupt_on={ "write_file": { "allowed_decisions": ["approve", "edit", "reject"], "when": writes_outside_workspace, }, "execute_sql": { "allowed_decisions": ["approve", "reject"], "when": is_write_query, }, }, ), ], checkpointer=InMemorySaver(), ) ``` When the `when` predicate returns `False`, the call runs without interrupting. When it returns `True`, or when you omit `when`, the call pauses as usual. Calls that evaluate to `False` are never added to the interrupt batch, so a reviewer only sees the actions that need a decision. ## Responding to interrupts When you invoke the agent, it runs until it either completes or an interrupt is raised. An interrupt is triggered when a tool call matches the policy you configured in `interrupt_on`. With `version="v2"`, the result is a `GraphOutput` with an `interrupts` attribute containing the actions that require review. You can then present those actions to a reviewer and resume execution once decisions are provided. ```python theme={null} from langgraph.types import Command # Human-in-the-loop leverages LangGraph's persistence layer. # You must provide a thread ID to associate the execution with a conversation thread, # so the conversation can be paused and resumed (as is needed for human review). config = {"configurable": {"thread_id": "some_id"}} # [!code highlight] # Run the graph until the interrupt is hit. result = agent.invoke( { "messages": [ { "role": "user", "content": "Delete old records from the database", } ] }, config=config, # [!code highlight] version="v2", # [!code highlight] ) # result is a GraphOutput with .value and .interrupts print(result.interrupts) # [!code highlight] # > ( # > Interrupt( # > value={ # > 'action_requests': [ # > { # > 'name': 'execute_sql', # > 'arguments': {'query': 'DELETE FROM records WHERE created_at < NOW() - INTERVAL \'30 days\';'}, # > 'description': 'Tool execution pending approval\n\nTool: execute_sql\nArgs: {...}' # > } # > ], # > 'review_configs': [ # > { # > 'action_name': 'execute_sql', # > 'allowed_decisions': ['approve', 'reject'] # > } # > ] # > } # > ), # > ) # Resume with approval decision agent.invoke( Command( # [!code highlight] resume={"decisions": [{"type": "approve"}]} # or "reject" [!code highlight] ), # [!code highlight] config=config, # Same thread ID to resume the paused conversation version="v2", ) ``` ### Decision types Use `approve` to approve the tool call as-is and execute it without changes. ```python theme={null} agent.invoke( Command( # Decisions are provided as a list, one per action under review. # The order of decisions must match the order of actions # in the interrupt request. resume={ "decisions": [ { "type": "approve", } ] } ), config=config, # Same thread ID to resume the paused conversation version="v2", ) ``` Use `edit` to modify the tool call before execution. Provide the edited action with the new tool name and arguments. ```python theme={null} agent.invoke( Command( # Decisions are provided as a list, one per action under review. # The order of decisions must match the order of actions # in the interrupt request. resume={ "decisions": [ { "type": "edit", # Edited action with tool name and args "edited_action": { # Tool name to call. # Will usually be the same as the original action. "name": "new_tool_name", # Arguments to pass to the tool. "args": {"key1": "new_value", "key2": "original_value"}, } } ] } ), config=config, # Same thread ID to resume the paused conversation version="v2", ) ``` When **editing** tool arguments, make changes conservatively. Significant modifications to the original arguments may cause the model to re-evaluate its approach and potentially execute the tool multiple times or take unexpected actions. Use `reject` to deny the tool call and provide feedback instead of execution. The tool is not executed. ```python theme={null} agent.invoke( Command( # Decisions are provided as a list, one per action under review. # The order of decisions must match the order of actions # in the interrupt request. resume={ "decisions": [ { "type": "reject", # Optional: explain why the action was rejected # and whether the agent should retry a different approach. "message": "User rejected this action. Do not retry this tool call.", } ] } ), config=config, # Same thread ID to resume the paused conversation version="v2", ) ``` The `message` is added to the conversation as feedback to help the agent understand why the action was rejected and what it should do instead. When you omit `message`, the middleware uses a default rejection message that tells the model the tool was not executed and not to retry the same tool call unless the user asks. For side-effecting tools, provide a domain-specific message that is explicit about whether the agent should abandon the action, ask a follow-up question, or try a safer alternative. Use `respond` for "ask user" style tools where the tool's real implementation is the human's reply. The `message` content is returned directly as the tool result; the tool itself is not executed. ```python theme={null} agent.invoke( Command( # Decisions are provided as a list, one per action under review. # The order of decisions must match the order of actions # in the interrupt request. resume={ "decisions": [ { "type": "respond", # The human's reply, returned directly as the tool result "message": "Blue.", } ] } ), config=config, # Same thread ID to resume the paused conversation version="v2", ) ``` The `message` is returned to the agent as a successful `ToolMessage`. Use `respond` when the tool is intentionally a placeholder for human input, for example, an `ask_user` tool that prompts for clarification. Do not use `respond` to deny a proposed action, because it tells the model that the tool completed successfully. *** ### Multiple decisions When multiple actions are under review, provide a decision for each action in the same order as they appear in the interrupt: ```python theme={null} { "decisions": [ {"type": "approve"}, { "type": "edit", "edited_action": { "name": "tool_name", "args": {"param": "new_value"} } }, { "type": "reject", "message": "This action is not allowed" } ] } ``` ## Streaming with human-in-the-loop You can stream real-time updates while the agent runs and handles interrupts using `stream_events()`. Use `stream.messages` to stream LLM tokens and `stream.values` to check agent state snapshots for interrupts. ```python theme={null} from langgraph.types import Command config = {"configurable": {"thread_id": "some_id"}} # Stream agent progress and LLM tokens until interrupt stream = agent.stream_events( {"messages": [{"role": "user", "content": "Delete old records from the database"}]}, config=config, version="v3", # [!code highlight] ) for message in stream.messages: # [!code highlight] for token in message.text: # [!code highlight] print(token, end="", flush=True) # Check whether the run paused for human input if stream.interrupted: # [!code highlight] print(f"\n\nInterrupt: {stream.interrupts}") # [!code highlight] # Resume with streaming after human decision stream = agent.stream_events( Command(resume={"decisions": [{"type": "approve"}]}), config=config, version="v3", # [!code highlight] ) for message in stream.messages: # [!code highlight] for token in message.text: print(token, end="", flush=True) ``` See the [Streaming](/oss/python/langchain/streaming) guide for more details on stream modes. ## Execution lifecycle The middleware defines an `after_model` hook that runs after the model generates a response but before any tool calls are executed: 1. The agent invokes the model to generate a response. 2. The middleware inspects the response for tool calls. 3. If any calls require human input, the middleware builds a `HITLRequest` with `action_requests` and `review_configs` and calls [interrupt](https://reference.langchain.com/python/langgraph/types/interrupt). 4. The agent waits for human decisions. 5. Based on the `HITLResponse` decisions, the middleware executes approved or edited calls, synthesizes [ToolMessage](https://reference.langchain.com/python/langchain-core/messages/tool/ToolMessage)'s for rejected calls, returns human replies directly as [ToolMessage](https://reference.langchain.com/python/langchain-core/messages/tool/ToolMessage)'s for `respond` decisions, and resumes execution. ## Custom HITL logic For more specialized workflows, you can build custom HITL logic directly using the [interrupt](https://reference.langchain.com/python/langgraph/types/interrupt) primitive and [middleware](/oss/python/langchain/middleware) abstraction. Review the [execution lifecycle](#execution-lifecycle) above to understand how to integrate interrupts into the agent's operation. ***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/human-in-the-loop.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).