人在环中

人在环中（HITL）中间件允许你为智能体（Agent）的工具调用添加人工监督。当模型提出一个可能需要审查的操作时——例如，写入文件或执行 SQL——该中间件可以暂停执行并等待决策。它通过根据可配置的策略检查每个工具调用来实现这一点。如果需要干预，中间件会发出一个 interrupt 中断以暂停执行。图（Graph）状态会使用 LangGraph 的持久化层保存，因此执行可以安全暂停并稍后恢复。随后，人工决策将决定接下来发生什么：操作可以原样批准（approve）、在运行前进行修改（edit）、附带反馈拒绝（reject），或者对于“询问用户”类工具，直接进行响应（respond）。

中断决策类型

该中间件定义了四种内置的人工响应中断的方式：

决策类型	描述	示例用例
✅ `approve`	使用代理提出的原始参数执行工具。	完全按照所写内容发送电子邮件草稿
✏️ `edit`	在执行前修改工具参数。	发送前更改收件人
❌ `reject`	完全跳过执行此工具调用，并向代理返回拒绝反馈。	拒绝文件删除并说明原因
💬 `respond`	将人类的消息直接作为合成工具结果返回，跳过执行，适用于“询问用户”类工具。	直接回复 `"ask_user"` 提示

每个工具可用的决策类型取决于你在 interrupt_on 中配置的策略。当多个工具调用同时被暂停时，每个操作都需要一个单独的决策。决策必须按照中断请求中操作出现的顺序提供。当人工拒绝所请求的操作时使用 respond。仅当人工作为工具本身（例如回答 ask_user 提示）时才使用 respond。不要使用 respond 来拒绝具有副作用的工具，因为其消息会被视为成功的工具结果。

编辑工具参数时，请谨慎更改。对原始参数进行重大修改可能会导致模型重新评估其方法，并可能多次执行工具或采取意外操作。

配置中断

要使用 HITL，请在创建智能体时将中间件添加到智能体的 middleware 列表中。你通过一个将工具操作映射到每个操作允许的决策类型的配置来对其进行设置。当工具调用匹配映射中的操作时，中间件将中断执行。

import { createAgent, humanInTheLoopMiddleware } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

const agent = createAgent({
    model: "gpt-5.5",
    tools: [writeFileTool, executeSQLTool, readDataTool],
    middleware: [
        humanInTheLoopMiddleware({
            interruptOn: {
                write_file: true, // 允许所有决策（批准、编辑、拒绝、响应）
                execute_sql: {
                    allowedDecisions: ["approve", "reject"],
                    // 不允许编辑
                    description: "🚨 SQL execution requires DBA approval",
                },
                // 安全操作，无需批准
                read_data: false,
            },
            // 中断消息的前缀 - 与工具名称和参数结合形成完整消息
            // 例如，"Tool execution pending approval: execute_sql with query='DELETE FROM...'"
            // 单个工具可以通过在其中断配置中指定 "description" 来覆盖此设置
            descriptionPrefix: "Tool execution pending approval",
        }),
    ],
    // 人在环中需要检查点来处理中断。
    // 在生产环境中，使用像 AsyncPostgresSaver 或 MongoDBSaver 这样的持久化检查点保存器。
    checkpointer: new MemorySaver(),
});

你必须配置一个检查点（checkpointer）来在中断之间持久化图的状态。在生产环境中，使用像 AsyncPostgresSaver 或 MongoDBSaver 这样的持久化检查点保存器。对于测试或原型开发，使用 InMemorySaver。调用智能体时，传递一个包含线程 ID 的 config，以将执行与对话线程关联。详见 LangGraph 中断文档。

配置选项

object

required

工具名称到批准配置的映射

工具批准配置选项：

boolean

default:"false"

是否允许批准

boolean

default:"false"

是否允许编辑

boolean

default:"false"

是否允许响应/拒绝

条件中断

默认情况下，interrupt_on 中列出的每个工具调用都会暂停以供审查。要仅暂停部分调用，请在工具的 InterruptOnConfig 中添加一个 when 谓词。该谓词接收一个 ToolCallRequest 并返回 True 表示中断或 False 表示自动批准，因此你可以根据工具的参数进行门控。条件中断目前仅在 Python 中可用。

响应中断

当你调用智能体时，它会运行直到完成或触发中断。当中断被触发时，工具调用与你在 interrupt_on 中配置的策略匹配。使用 version="v2" 时，结果是一个 GraphOutput，其 interrupts 属性包含需要审查的操作。然后，你可以将这些操作呈现给审查者，并在提供决策后恢复执行。

import { HumanMessage } from "@langchain/core/messages";
import { Command } from "@langchain/langgraph";

// 你必须提供一个线程 ID 来将执行与对话线程关联，
// 这样对话才能暂停和恢复（正如人工审查所需）。
const config = { configurable: { thread_id: "some_id" } };

// 运行图直到触发中断。
const result = await agent.invoke(
    {
        messages: [new HumanMessage("删除数据库中的旧记录")],
    },
    config 
);


// 中断包含完整的 HITL 请求，包括 actionRequests 和 reviewConfigs
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']
// >             }
// >          ]
// >       }
// >    )
// > ]

// 使用批准决策恢复执行
await agent.invoke(
    new Command({
        resume: { decisions: [{ type: "approve" }] }, // 或 "reject"
    }),
    config // 使用相同的线程 ID 来恢复暂停的对话
);

决策类型

✅ 批准
✏️ 编辑
❌ 拒绝
💬 响应

使用 approve 来原样批准工具调用并执行，不做任何更改。

await agent.invoke(
    new Command({
        // 决策以列表形式提供，每个正在审查的操作一个。
        // 决策的顺序必须与中断请求中操作的顺序匹配。
        resume: {
            decisions: [
                {
                    type: "approve",
                }
            ]
        }
    }),
    config  // 使用相同的线程 ID 来恢复暂停的对话
);

使用 edit 在执行前修改工具调用。提供编辑后的操作，包括新的工具名称和参数。

await agent.invoke(
    new Command({
        // 决策以列表形式提供，每个正在审查的操作一个。
        // 决策的顺序必须与中断请求中操作的顺序匹配。
        resume: {
            decisions: [
                {
                    type: "edit",
                    // 包含工具名称和参数的编辑后操作
                    editedAction: {
                        // 要调用的工具名称。
                        // 通常与原始操作相同。
                        name: "new_tool_name",
                        // 传递给工具的参数。
                        args: { key1: "new_value", key2: "original_value" },
                    }
                }
            ]
        }
    }),
    config  // 使用相同的线程 ID 来恢复暂停的对话
);

编辑工具参数时，请谨慎更改。对原始参数进行重大修改可能会导致模型重新评估其方法，并可能多次执行工具或采取意外操作。

使用 reject 来拒绝工具调用，并提供反馈而不是执行。工具不会被执行。

await agent.invoke(
    new Command({
        // 决策以列表形式提供，每个正在审查的操作一个。
        // 决策的顺序必须与中断请求中操作的顺序匹配。
        resume: {
            decisions: [
                {
                    type: "reject",
                    // 可选：解释为什么拒绝该操作
                    // 以及智能体是否应该尝试不同的方法。
                    message: "用户拒绝了此操作。请勿重试此工具调用。",
                }
            ]
        }
    }),
    config  // 使用相同的线程 ID 来恢复暂停的对话
);

message 会作为反馈添加到对话中，以帮助智能体理解操作被拒绝的原因以及它应该如何做。当你省略 message 时，中间件会使用默认的拒绝消息，告知模型工具未执行且除非用户要求，否则不要重试相同的工具调用。对于具有副作用的工具，请提供明确的消息，说明智能体是应放弃该操作、提出后续问题，还是尝试更安全的替代方案。

respond 用于“询问用户”类工具，其真正的实现是人工的回复。message 内容直接作为工具结果返回；工具本身不会被执行。

await agent.invoke(
    new Command({
        // 决策以列表形式提供，每个正在审查的操作一个。
        // 决策的顺序必须与中断请求中操作的顺序匹配。
        resume: {
            decisions: [
                {
                    type: "respond",
                    // 人工的回复，直接作为工具结果返回
                    message: "蓝色。",
                }
            ]
        }
    }),
    config  // 使用相同的线程 ID 来恢复暂停的对话
);

message 会作为成功的 ToolMessage 返回给智能体。当工具本质上是人工输入的占位符时（例如，用于提示澄清的 ask_user 工具），使用 respond。不要使用 respond 来拒绝提议的操作，因为它会告知模型该工具已成功完成。

多个决策

当有多个操作正在审查时，请按照它们在中断中出现的顺序为每个操作提供一个决策：

{
    decisions: [
        { type: "approve" },
        {
            type: "edit",
            editedAction: {
                name: "tool_name",
                args: { param: "new_value" }
            }
        },
        {
            type: "reject",
            message: "此操作不被允许"
        }
    ]
}

结合人在环中进行流式处理

你可以使用 stream_events() 在智能体运行和处理中断时流式传输实时更新。使用 stream.messages 流式传输 LLM 令牌，使用 stream.values 检查智能体状态快照以获取中断。

import { Command } from "@langchain/langgraph";

const config = { configurable: { thread_id: "some_id" } };

// 流式传输智能体进度和 LLM 令牌，直到中断
const stream = await agent.streamEvents(
    { messages: [{ role: "user", content: "删除数据库中的旧记录" }] },
    { ...config, version: "v3" }
);
for await (const message of stream.messages) {
    for await (const token of message.text) {
        process.stdout.write(token);
    }
}

// 检查运行是否因人工输入而暂停
if (stream.interrupted) {
    console.log(`\n\n中断: ${JSON.stringify(stream.interrupts)}`);
}

// 人工决策后恢复流式传输
const resumeStream = await agent.streamEvents(
    new Command({ resume: { decisions: [{ type: "approve" }] } }),
    { ...config, version: "v3" }
);
for await (const message of resumeStream.messages) {
    for await (const token of message.text) {
        process.stdout.write(token);
    }
}

关于流模式的更多细节，请参阅流式传输指南。

执行生命周期

该中间件定义了一个 after_model 钩子，它在模型生成响应之后但在任何工具调用执行之前运行：

智能体调用模型以生成响应。
中间件检查响应中的工具调用。
如果任何调用需要人工输入，中间件会构建一个包含 action_requests 和 review_configs 的 HITLRequest，并调用 interrupt。
智能体等待人工决策。
根据 HITLResponse 决策，中间件执行已批准或已编辑的调用，为被拒绝的调用合成 ToolMessage，将人工的回复直接作为 ToolMessage 返回（针对 respond 决策），并恢复执行。

自定义 HITL 逻辑

对于更专业的工作流，你可以直接使用 interrupt 原语和中间件抽象来构建自定义的 HITL 逻辑。请查阅上面的执行生命周期，以了解如何将中断集成到智能体的操作中。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

中断决策类型

配置中断

条件中断

响应中断

决策类型

多个决策

结合人在环中进行流式处理

执行生命周期

自定义 HITL 逻辑

​中断决策类型

​配置中断

​条件中断

​响应中断

​决策类型

​多个决策

​结合人在环中进行流式处理

​执行生命周期

​自定义 HITL 逻辑

中断决策类型

配置中断

条件中断

响应中断

决策类型

多个决策

结合人在环中进行流式处理

执行生命周期

自定义 HITL 逻辑