人机协同

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

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

人类决策随后确定接下来会发生什么：动作可以按原样批准（approve），在运行前修改（edit），或者拒绝并给出反馈（reject）。

中断决策类型

中间件定义了三种人类可以响应中断的内置方式：

决策类型	描述	示例用例
✅ approve	行动被批准并按原样执行，不进行任何更改。	按照原文发送一封电子邮件草稿
✏️ edit	工具调用执行时进行修改。	在发送电子邮件之前更改收件人
❌ reject	工具调用被拒绝，并在对话中添加解释。	拒绝电子邮件草稿并解释如何重写

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

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

配置中断

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

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

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware 
from langgraph.checkpoint.memory import InMemorySaver 


agent = create_agent(
    model="openai:gpt-4o",
    tools=[write_file_tool, execute_sql_tool, read_data_tool],
    middleware=[
        HumanInTheLoopMiddleware( 
            interrupt_on={
                "write_file": True,  # All decisions (approve, edit, reject) allowed
                "execute_sql": {"allowed_decisions": ["approve", "reject"]},  # No editing allowed
                # Safe operation, no approval needed
                "read_data": False,
            },
            # Prefix for interrupt messages - combined with tool name and args to form the full message
            # e.g., "Tool execution pending approval: execute_sql with query='DELETE FROM...'"
            # Individual tools can override this by specifying a "description" in their interrupt config
            description_prefix="Tool execution pending approval",
        ),
    ],
    # Human-in-the-loop requires checkpointing to handle interrupts.
    # In production, use a persistent checkpointer like AsyncPostgresSaver.
    checkpointer=InMemorySaver(),  
)

您必须配置一个检查点以在中断期间持久化图状态。 在生产环境中，使用持久化检查点，例如AsyncPostgresSaver。对于测试或原型设计，使用InMemorySaver。

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

响应中断

当您调用智能体时，它会运行直到完成或发生中断。当工具调用与您在 interrupt_on 中配置的策略匹配时，将触发中断。在这种情况下，调用结果将包含一个 __interrupt__ 字段，其中包含需要审查的操作。然后，您可以向审查员展示这些操作，并在提供决策后继续执行。

from langgraph.types import Command

# Human-in-the-loop leverages LangGraph's persistence layer.
# You must provide a thread ID to associate the execution with a conversation thread,
# so the conversation can be paused and resumed (as is needed for human review).
config = {"configurable": {"thread_id": "some_id"}} 
# Run the graph until the interrupt is hit.
result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Delete old records from the database",
            }
        ]
    },
    config=config 
)

# The interrupt contains the full HITL request with action_requests and review_configs
print(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']
# >             }
# >          ]
# >       }
# >    )
# > ]


# Resume with approval decision
agent.invoke(
    Command( 
        resume={"decisions": [{"type": "approve"}]}  # or "edit", "reject"
    ), 
    config=config # Same thread ID to resume the paused conversation
)

决策类型

✅ approve

使用 approve 直接批准工具调用并执行，无需更改。

agent.invoke(
    Command(
        # Decisions are provided as a list, one per action under review.
        # The order of decisions must match the order of actions
        # listed in the `__interrupt__` request.
        resume={
            "decisions": [
                {
                    "type": "approve",
                }
            ]
        }
    ),
    config=config  # Same thread ID to resume the paused conversation
)

✏️ edit

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

agent.invoke(
    Command(
        # Decisions are provided as a list, one per action under review.
        # The order of decisions must match the order of actions
        # listed in the `__interrupt__` request.
        resume={
            "decisions": [
                {
                    "type": "edit",
                    # Edited action with tool name and args
                    "edited_action": {
                        # Tool name to call.
                        # Will usually be the same as the original action.
                        "name": "new_tool_name",
                        # Arguments to pass to the tool.
                        "args": {"key1": "new_value", "key2": "original_value"},
                    }
                }
            ]
        }
    ),
    config=config  # Same thread ID to resume the paused conversation
)

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

❌ reject

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

agent.invoke(
    Command(
        # Decisions are provided as a list, one per action under review.
        # The order of decisions must match the order of actions
        # listed in the `__interrupt__` request.
        resume={
            "decisions": [
                {
                    "type": "reject",
                    # An explanation about why the action was rejected
                    "message": "No, this is wrong because ..., instead do this ...",
                }
            ]
        }
    ),
    config=config  # Same thread ID to resume the paused conversation
)

message 被添加到对话中作为反馈，以帮助智能体理解为什么该操作被拒绝以及它应该采取什么替代行动。

---

多个决策

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

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

执行生命周期

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

1. 智能体调用模型生成响应。
2. 中间件检查响应中的工具调用。
3. 如果有任何调用需要人工输入，中间件将使用 HITLRequest、action_requests 和 review_configs 构建一个 HITLRequest 并调用 中断。
4. 智能体等待人工决策。
5. 根据基于 HITLResponse 的决策，中间件执行批准或编辑后的调用，为拒绝的调用合成 工具消息，并继续执行。

自定义HITL逻辑

对于更专业的流程，您可以直接使用 中断 原语和 中间件 抽象来构建自定义的 HITL 逻辑。

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

---

在GitHub上编辑此页面的源代码.

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