> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-opensw-1783460346-e74075c.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/javascript/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/javascript/langchain-langgraph/index/interrupt) that halts execution. The graph state is saved using LangGraph's [persistence layer](/oss/javascript/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/javascript/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/javascript/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. ```ts theme={null} import { createAgent, humanInTheLoopMiddleware } from "langchain"; // [!code highlight] import { MemorySaver } from "@langchain/langgraph"; // [!code highlight] const agent = createAgent({ model: "gpt-5.5", tools: [writeFileTool, executeSQLTool, readDataTool], middleware: [ humanInTheLoopMiddleware({ interruptOn: { write_file: true, // All decisions (approve, edit, reject, respond) allowed execute_sql: { allowedDecisions: ["approve", "reject"], // No editing allowed description: "🚨 SQL execution requires DBA approval", }, // Safe operation, no approval needed read_data: false, }, // 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 descriptionPrefix: "Tool execution pending approval", }), ], // Human-in-the-loop requires checkpointing to handle interrupts. // In production, use a persistent checkpointer like AsyncPostgresSaver. checkpointer: new MemorySaver(), // [!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/javascript/classes/_langchain_langgraph-checkpoint-postgres.AsyncPostgresSaver.html). For testing or prototyping, use [`InMemorySaver`](https://reference.langchain.com/javascript/classes/_langchain_langgraph-checkpoint.MemorySaver.html). 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/javascript/langgraph/interrupts) for details. Mapping of tool names to approval configs **Tool approval config options:** Whether approval is allowed Whether editing is allowed Whether responding/rejection is allowed ## 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 are currently available in Python only. ## 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. ```typescript theme={null} import { HumanMessage } from "@langchain/core/messages"; import { Command } from "@langchain/langgraph"; // 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). const config = { configurable: { thread_id: "some_id" } }; // [!code highlight] // Run the graph until the interrupt is hit. const result = await agent.invoke( { messages: [new HumanMessage("Delete old records from the database")], }, config // [!code highlight] ); // The interrupt contains the full HITL request with action_requests and review_configs console.log(result.__interrupt__); // > [ // > Interrupt( // > value: { // > actionRequests: [ // > { // > 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: {...}' // > } // > ], // > reviewConfigs: [ // > { // > actionName: 'execute_sql', // > allowedDecisions: ['approve', 'reject'] // > } // > ] // > } // > ) // > ] // Resume with approval decision await agent.invoke( new Command({ // [!code highlight] resume: { decisions: [{ type: "approve" }] }, // or "reject" [!code highlight] }), // [!code highlight] config // Same thread ID to resume the paused conversation ); ``` ### Decision types Use `approve` to approve the tool call as-is and execute it without changes. ```typescript theme={null} await agent.invoke( new 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 // Same thread ID to resume the paused conversation ); ``` Use `edit` to modify the tool call before execution. Provide the edited action with the new tool name and arguments. ```typescript theme={null} await agent.invoke( new 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 editedAction: { // 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 // Same thread ID to resume the paused conversation ); ``` 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. ```typescript theme={null} await agent.invoke( new 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 // Same thread ID to resume the paused conversation ); ``` 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. ```typescript theme={null} await agent.invoke( new 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 // Same thread ID to resume the paused conversation ); ``` 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: ```typescript theme={null} { decisions: [ { type: "approve" }, { type: "edit", editedAction: { 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. ```typescript theme={null} import { Command } from "@langchain/langgraph"; const config = { configurable: { thread_id: "some_id" } }; // Stream agent progress and LLM tokens until interrupt const stream = await agent.streamEvents( { messages: [{ role: "user", content: "Delete old records from the database" }] }, { ...config, version: "v3" } // [!code highlight] ); for await (const message of stream.messages) { // [!code highlight] for await (const token of message.text) { // [!code highlight] process.stdout.write(token); } } // Check whether the run paused for human input if (stream.interrupted) { // [!code highlight] console.log(`\n\nInterrupt: ${JSON.stringify(stream.interrupts)}`); // [!code highlight] } // Resume with streaming after human decision const resumeStream = await agent.streamEvents( new Command({ resume: { decisions: [{ type: "approve" }] } }), { ...config, version: "v3" } // [!code highlight] ); for await (const message of resumeStream.messages) { // [!code highlight] for await (const token of message.text) { process.stdout.write(token); } } ``` See the [Streaming](/oss/javascript/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/javascript/langchain-langgraph/index/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/javascript/langchain-core/messages/ToolMessage)'s for rejected calls, returns human replies directly as [ToolMessage](https://reference.langchain.com/javascript/langchain-core/messages/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/javascript/langchain-langgraph/index/interrupt) primitive and [middleware](/oss/javascript/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).