人机协作

人机协作（HITL）中间件让你为智能体工具调用添加人工监督。当模型提出可能需要审查的操作时——例如写入文件或执行 SQL——中间件可以暂停执行并等待决定。

它通过将每个工具调用与可配置的策略进行比对来实现这一点。如果需要干预，中间件会发出一个 interrupt 来暂停执行。图状态通过 LangGraph 的持久化层保存，因此执行可以安全暂停并在稍后恢复。

然后，人工决定决定接下来会发生什么：操作可以按原样批准（approve）、在运行前修改（edit）、带反馈拒绝（reject），或直接响应（respond）用于”询问用户”类型的工具。

中断决策类型

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

决策类型	描述	示例用例
✅ approve	操作按原样批准并执行，不做任何更改。	按原样发送邮件草稿
✏️ edit	工具调用在修改后执行。	在发送邮件前更改收件人
❌ reject	工具调用被拒绝，并在对话中添加解释。	拒绝邮件草稿并解释如何重写
💬 respond	跳过工具执行；人工的消息成为工具结果。	用直接回复回答”ask_user”提示

每个工具的可用决策类型取决于你在 interrupt_on 中配置的策略。当同时暂停多个工具调用时，每个操作需要单独的决策。决策必须按照操作在中断请求中出现的顺序提供。

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

配置中断

要使用人机协作，在创建智能体时将中间件添加到智能体的 middleware 列表中。

你需要配置工具操作到允许的决策类型的映射。当工具调用匹配映射中的操作时，中间件将中断执行。

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

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

你必须配置检查点器以在中断之间持久化图状态。 在生产中，使用持久化检查点器如 AsyncPostgresSaver。对于测试或原型开发，使用 InMemorySaver。

调用智能体时，传递包含线程 ID 的 config，以将执行与对话线程关联。 详情请参阅 LangGraph 中断文档。

配置选项

interruptOn · object · required

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

工具审批配置选项：

allowAccept · boolean · default: "false"

是否允许批准

allowEdit · boolean · default: "false"

是否允许编辑

allowRespond · boolean · default: "false"

是否允许响应/拒绝

响应中断

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

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("Delete old records from the database")],
    },
    config 
);


// 中断包含完整的 HITL 请求，包括 action_requests 和 review_configs
console.log(result.__interrupt__);
// > [
// >    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']
// >             }
// >          ]
// >       }
// >    )
// > ]

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

决策类型

✅ approve

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

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

✏️ edit

使用 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

使用 reject 拒绝工具调用并提供反馈而非执行。

await agent.invoke(
    new Command({
        // 决策以列表形式提供，每个待审查操作一个。
        // 决策的顺序必须与中断请求中操作的顺序匹配。
        resume: {
            decisions: [
                {
                    type: "reject",
                    // 关于为什么拒绝操作的解释
                    message: "No, this is wrong because ..., instead do this ...",
                }
            ]
        }
    }),
    config  // 使用相同的线程 ID 恢复暂停的对话
);

message 作为反馈添加到对话中，帮助智能体理解为什么操作被拒绝以及它应该怎么做。

---

多个决策

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

{
    decisions: [
        { type: "approve" },
        {
            type: "edit",
            editedAction: {
                name: "tool_name",
                args: { param: "new_value" }
            }
        },
        {
            type: "reject",
            message: "This action is not allowed"
        }
    ]
}

💬 respond

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

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

message 作为成功的 ToolMessage 返回给智能体。当工具有意作为人工输入的占位符时使用 respond——例如，一个提示澄清的 ask_user 工具。

使用人机协作进行流式输出

你可以使用 stream() 代替 invoke() 来在智能体运行和处理中断时获取实时更新。使用 stream_mode=['updates', 'messages'] 配合 version="v2" 以统一的 v2 格式同时流式传输智能体进度和 LLM Token。

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

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

// 流式传输智能体进度和 LLM Token 直到中断
for await (const [mode, chunk] of await agent.stream(
    { messages: [{ role: "user", content: "Delete old records from the database" }] },
    { ...config, streamMode: ["updates", "messages"] }
)) {
    if (mode === "messages") {
        // LLM Token
        const [token, metadata] = chunk;
        if (token.content) {
            process.stdout.write(token.content);
        }
    } else if (mode === "updates") {
        // 检查中断
        if ("__interrupt__" in chunk) {
            console.log(`\n\n中断：${JSON.stringify(chunk.__interrupt__)}`);
        }
    }
}

// 在人工决策后以流式方式恢复
for await (const [mode, chunk] of await agent.stream(
    new Command({ resume: { decisions: [{ type: "approve" }] } }),
    { ...config, streamMode: ["updates", "messages"] }
)) {
    if (mode === "messages") {
        const [token, metadata] = chunk;
        if (token.content) {
            process.stdout.write(token.content);
        }
    }
}

有关流模式的更多详细信息，请参阅流式输出指南。

执行生命周期

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

1. 智能体调用模型生成响应。
2. 中间件检查响应中的工具调用。
3. 如果任何调用需要人工输入，中间件构建一个带有 action_requests 和 review_configs 的 HITLRequest 并调用 interrupt。
4. 智能体等待人工决策。
5. 根据 HITLResponse 决策，中间件执行已批准或已编辑的调用，为已拒绝的调用合成 ToolMessage，对于 respond 决策直接返回人工回复作为 ToolMessage，然后恢复执行。

自定义人机协作逻辑

对于更专业的工作流，你可以直接使用 interrupt 原语和中间件抽象构建自定义人机协作逻辑。

请查看上方的执行生命周期以了解如何将中断集成到智能体的操作中。

---

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。