> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Human in the Loop

Human in the Loop（HITL）[中间件](/oss/javascript/langchain/middleware/built-in#human-in-the-loop)允许你为代理工具调用添加人工监督。
当模型提出可能需要审查的操作时——例如写入文件或执行SQL——该中间件可以暂停执行并等待决策。

它通过根据可配置的策略检查每个工具调用来实现这一点。如果需要干预，中间件会发出一个[中断](https://reference.langchain.com/javascript/langchain-langgraph/index/interrupt)，暂停执行。图状态使用LangGraph的[持久化层](/oss/javascript/langgraph/persistence)保存，因此执行可以安全地暂停并在稍后恢复。

然后，人工决策决定下一步操作：操作可以按原样批准（`approve`）、在运行前修改（`edit`）、拒绝并提供反馈（`reject`），或直接响应（`respond`）用于“询问用户”类型的工具。

## 中断决策类型

[中间件](/oss/javascript/langchain/middleware/built-in#human-in-the-loop)定义了四种内置的人工响应中断的方式：

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

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

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

## 配置中断

要使用HITL，请在创建代理时将[中间件](/oss/javascript/langchain/middleware/built-in#human-in-the-loop)添加到代理的 `middleware` 列表中。

你通过将工具操作映射到每个操作允许的决策类型来进行配置。当工具调用与映射中的操作匹配时，中间件将中断执行。

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createAgent, humanInTheLoopMiddleware } from "langchain"; // [!code highlight]
import { MemorySaver } from "@langchain/langgraph"; // [!code highlight]

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(), // [!code highlight]
});
```

<Info>
  你必须配置检查点以在中断期间持久化图状态。
  在生产环境中，使用持久化检查点，如 [`AsyncPostgresSaver`](https://reference.langchain.com/javascript/classes/_langchain_langgraph-checkpoint-postgres.AsyncPostgresSaver.html)。对于测试或原型设计，使用 [`InMemorySaver`](https://reference.langchain.com/javascript/classes/_langchain_langgraph-checkpoint.MemorySaver.html)。

  调用代理时，传递一个包含**线程ID**的 `config`，以将执行与对话线程关联。
  详情请参阅 [LangGraph 中断文档](/oss/javascript/langgraph/interrupts)。
</Info>

<Accordion title="配置选项">
  <ParamField body="interruptOn" type="object" required>
    工具名称到批准配置的映射
  </ParamField>

  **工具批准配置选项：**

  <ParamField body="allowAccept" type="boolean" default="false">
    是否允许批准
  </ParamField>

  <ParamField body="allowEdit" type="boolean" default="false">
    是否允许编辑
  </ParamField>

  <ParamField body="allowRespond" type="boolean" default="false">
    是否允许响应/拒绝
  </ParamField>
</Accordion>

## 响应中断

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

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { HumanMessage } from "@langchain/core/messages";
import { Command } from "@langchain/langgraph";

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

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

// 中断包含完整的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({
    // [!code highlight]
    resume: { decisions: [{ type: "approve" }] }, // 或 "reject" [!code highlight]
  }), // [!code highlight]
  config, // 相同的线程ID以恢复暂停的对话
);
```

### 决策类型

<Tabs>
  <Tab title="✅ approve">
    使用 `approve` 来批准工具调用并按原样执行，不做更改。

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

  <Tab title="✏️ edit">
    使用 `edit` 在执行前修改工具调用。
    提供带有新工具名称和参数的已编辑操作。

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

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

  <Tab title="❌ reject">
    使用 `reject` 来拒绝工具调用并提供反馈，而不是执行。

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    await agent.invoke(
        new Command({
            // 决策以列表形式提供，每个待审查操作一个。
            // 决策的顺序必须与中断请求中操作的顺序匹配。
            resume: {
                decisions: [
                    {
                        type: "reject",
                        // 关于操作被拒绝原因的解释
                        message: "不，这是错误的，因为...，应该这样做...",
                    }
                ]
            }
        }),
        config  // 相同的线程ID以恢复暂停的对话
    );
    ```

    `message` 作为反馈添加到对话中，以帮助代理理解操作被拒绝的原因以及应该做什么。

    ***

    ### 多个决策

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

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      decisions: [
        { type: "approve" },
        {
          type: "edit",
          editedAction: {
            name: "tool_name",
            args: { param: "new_value" },
          },
        },
        {
          type: "reject",
          message: "此操作不允许",
        },
      ];
    }
    ```
  </Tab>

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

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

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

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

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

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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"] }, // [!code highlight]
)) {
  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);
    }
  }
}
```

有关流模式的更多详情，请参阅[流式传输](/oss/javascript/langchain/streaming)指南。

## 执行生命周期

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

1. 代理调用模型生成响应。
2. 中间件检查响应中的工具调用。
3. 如果任何调用需要人工输入，中间件会构建一个包含 `action_requests` 和 `review_configs` 的 `HITLRequest`，并调用 [interrupt](https://reference.langchain.com/javascript/langchain-langgraph/index/interrupt)。
4. 代理等待人工决策。
5. 基于 `HITLResponse` 决策，中间件执行批准或编辑的调用，为拒绝的调用合成 [ToolMessage](https://reference.langchain.com/javascript/langchain-core/messages/ToolMessage)，对于 `respond` 决策直接将人工回复作为 [ToolMessage](https://reference.langchain.com/javascript/langchain-core/messages/ToolMessage) 返回，并恢复执行。

## 自定义HITL逻辑

对于更专业的工作流，你可以直接使用 [interrupt](https://reference.langchain.com/javascript/langchain-langgraph/index/interrupt) 原语和 [中间件](/oss/javascript/langchain/middleware) 抽象构建自定义HITL逻辑。

请查阅上面的[执行生命周期](#执行生命周期)以了解如何将中断集成到代理的操作中。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到Claude、VSCode等，通过MCP获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在GitHub上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/human-in-the-loop.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>