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

# 人机协作

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

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

然后由人工决策决定接下来的操作：可以按原样批准操作（`approve`）、在运行前修改（`edit`）、带反馈拒绝（`reject`），或直接回复（`respond`）用于"询问用户"类型的工具。

## 中断决策类型

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

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

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

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

## 配置中断

要使用人机协作，在创建智能体时将[中间件](/oss/python/langchain/middleware/built-in#human-in-the-loop)添加到智能体的 `middleware` 列表中。

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware # [!code highlight]
from langgraph.checkpoint.memory import InMemorySaver # [!code highlight]


agent = create_agent(
    model="gpt-5.4",
    tools=[write_file, execute_sql, read_data],
    middleware=[
        HumanInTheLoopMiddleware( # [!code highlight]
            interrupt_on={
                "write_file": True,  # 允许所有决策（approve、edit、reject、respond）
                "execute_sql": {"allowed_decisions": ["approve", "reject"]},  # 不允许编辑
                "read_data": False, # 安全操作，无需审批
            },
            # 中断消息的前缀 - 与工具名称和参数组合形成完整消息
            # 例如，"Tool execution pending approval: execute_sql with query='DELETE FROM...'"
            # 单个工具可以通过在其中断配置中指定 "description" 来覆盖此前缀
            description_prefix="Tool execution pending approval",
        ),
    ],
    # 人机协作需要检查点来处理中断。
    # 在生产环境中，使用持久化检查点器如 AsyncPostgresSaver。
    checkpointer=InMemorySaver(),  # [!code highlight]
)
```

<Info>
  你必须配置检查点器以在中断之间持久化图状态。
  在生产环境中，使用持久化检查点器如 [`AsyncPostgresSaver`](https://reference.langchain.com/python/langgraph/checkpoints/#langgraph.checkpoint.postgres.aio.AsyncPostgresSaver)。对于测试或原型开发，使用 [`InMemorySaver`](https://reference.langchain.com/python/langgraph/checkpoints/#langgraph.checkpoint.memory.InMemorySaver)。

  调用智能体时，传入包含 **线程 ID** 的 `config`，以将执行与对话线程关联。
  详情请参见 [LangGraph 中断文档](/oss/python/langgraph/interrupts)。
</Info>

<Accordion title="配置选项">
  <ParamField body="interrupt_on" type="dict" required>
    工具名称到审批配置的映射。值可以是 `True`（使用默认配置中断）、`False`（自动批准）或 `InterruptOnConfig` 对象。
  </ParamField>

  <ParamField body="description_prefix" type="string" default="Tool execution requires approval">
    操作请求描述的前缀
  </ParamField>

  **`InterruptOnConfig` 选项：**

  <ParamField body="allowed_decisions" type="list[string]">
    允许的决策列表：`'approve'`、`'edit'`、`'reject'` 或 `'respond'`
  </ParamField>

  <ParamField body="description" type="string | callable">
    静态字符串或可调用函数，用于自定义描述
  </ParamField>
</Accordion>

## 响应中断

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langgraph.types import Command

# 人机协作利用 LangGraph 的持久化层。
# 你必须提供线程 ID 以将执行与对话线程关联，
# 这样对话才能暂停和恢复（人工审查所需）。
config = {"configurable": {"thread_id": "some_id"}} # [!code highlight]
# 运行图直到触发中断。
result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Delete old records from the database",
            }
        ]
    },
    config=config, # [!code highlight]
    version="v2", # [!code highlight]
)

# result 是一个带有 .value 和 .interrupts 的 GraphOutput
print(result.interrupts)  # [!code highlight]
# > (
# >    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']
# >             }
# >          ]
# >       }
# >    ),
# > )


# 使用批准决策恢复执行
agent.invoke(
    Command( # [!code highlight]
        resume={"decisions": [{"type": "approve"}]}  # 或 "reject" [!code highlight]
    ), # [!code highlight]
    config=config, # 相同的线程 ID 以恢复暂停的对话
    version="v2",
)
```

### 决策类型

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

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

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

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

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

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

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    agent.invoke(
        Command(
            # 决策以列表形式提供，每个待审查的操作对应一个。
            # 决策的顺序必须与中断请求中操作的顺序匹配。
            resume={
                "decisions": [
                    {
                        "type": "reject",
                        # 关于操作被拒绝原因的解释
                        "message": "No, this is wrong because ..., instead do this ...",
                    }
                ]
            }
        ),
        config=config,  # 相同的线程 ID 以恢复暂停的对话
        version="v2",
    )
    ```

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

    ***

    ### 多个决策

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

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
        "decisions": [
            {"type": "approve"},
            {
                "type": "edit",
                "edited_action": {
                    "name": "tool_name",
                    "args": {"param": "new_value"}
                }
            },
            {
                "type": "reject",
                "message": "This action is not allowed"
            }
        ]
    }
    ```
  </Tab>

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

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

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

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

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langgraph.types import Command

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

# 流式传输智能体进度和 LLM Token 直到中断
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "Delete old records from the database"}]},
    config=config,
    stream_mode=["updates", "messages"],  # [!code highlight]
    version="v2",  # [!code highlight]
):
    if chunk["type"] == "messages":  # [!code highlight]
        # LLM Token
        token, metadata = chunk["data"]  # [!code highlight]
        if token.content:
            print(token.content, end="", flush=True)
    elif chunk["type"] == "updates":  # [!code highlight]
        # 检查中断
        if "__interrupt__" in chunk["data"]:  # [!code highlight]
            print(f"\n\n中断: {chunk['data']['__interrupt__']}")

# 在人工决策后使用流式传输恢复
for chunk in agent.stream(
    Command(resume={"decisions": [{"type": "approve"}]}),
    config=config,
    stream_mode=["updates", "messages"],
    version="v2",  # [!code highlight]
):
    if chunk["type"] == "messages":  # [!code highlight]
        token, metadata = chunk["data"]  # [!code highlight]
        if token.content:
            print(token.content, end="", flush=True)
```

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

## 执行生命周期

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

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

## 自定义人机协作逻辑

对于更专门的工作流程，你可以直接使用 [interrupt](https://reference.langchain.com/python/langgraph/types/interrupt) 原语和[中间件](/oss/python/langchain/middleware)抽象来构建自定义人机协作逻辑。

查看上面的[执行生命周期](#execution-lifecycle)以了解如何将中断集成到智能体的操作中。

***

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