Human in the Loop - Docs by LangChain

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

中断决策类型

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

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

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

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

配置中断

要使用HITL，请在创建代理时将中间件添加到代理的 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，参数为 query='DELETE FROM...'"
      // 单个工具可以通过在其中断配置中指定 "description" 来覆盖此设置
      descriptionPrefix: "工具执行待批准",
    }),
  ],
  // Human in the Loop需要检查点来处理中断。
  // 在生产环境中，使用持久化检查点，如 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("从数据库中删除旧记录")],
  },
  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: '工具执行待批准\n\n工具: execute_sql\n参数: {...}'
// >             }
// >          ],
// >          review_configs: [
// >             {
// >                action_name: 'execute_sql',
// >                allowed_decisions: ['approve', 'reject']
// >             }
// >          ]
// >       }
// >    )
// > ]

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

决策类型

✅ approve
✏️ edit
❌ reject
💬 respond

使用 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 作为反馈添加到对话中，以帮助代理理解操作被拒绝的原因以及应该做什么。

多个决策

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

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

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

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

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

使用Human in the Loop进行流式传输

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

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

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

// 流式传输代理进度和LLM令牌直到中断
for await (const [mode, chunk] of await agent.stream(
  { messages: [{ role: "user", content: "从数据库中删除旧记录" }] },
  { ...config, streamMode: ["updates", "messages"] },
)) {
  if (mode === "messages") {
    // LLM令牌
    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 钩子，该钩子在模型生成响应后但在任何工具调用执行前运行：

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

自定义HITL逻辑

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

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

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

​中断决策类型

​配置中断

​响应中断

​决策类型

​多个决策

​使用Human in the Loop进行流式传输

​执行生命周期

​自定义HITL逻辑

中断决策类型

配置中断

响应中断

决策类型

多个决策

使用Human in the Loop进行流式传输

执行生命周期

自定义HITL逻辑