人机协作（HITL）中间件允许您在智能体工具调用中添加人工监督。
当模型提出可能需要审查的操作时——例如写入文件或执行SQL——中间件可以暂停执行并等待决策。
它通过检查每个工具调用与可配置策略进行匹配来实现这一点。如果需要干预，中间件会发出一个中断，以停止执行。图状态使用LangGraph的持久化层进行保存，因此可以安全地暂停执行并在稍后恢复。
人类决策随后确定接下来会发生什么：动作可以按原样批准（approve），在运行前修改（edit），或者拒绝并给出反馈（reject）。
中断决策类型
中间件定义了三种人类对中断进行响应的内置方式：
| 决策类型 | 描述 | 示例用例 |
|---|
✅ approve | 行动被批准并按原样执行，不进行任何更改。 | 按照原文发送一封电子邮件草稿 |
✏️ edit | 工具调用执行时进行了修改。 | 在发送电子邮件之前更改收件人 |
❌ reject | 工具调用被拒绝，并在对话中添加了解释。 | 拒绝电子邮件草稿并解释如何重写 |
interrupt_on 中配置的策略。
当多个工具调用同时暂停时，每个操作都需要一个单独的决策。
决策必须按照中断请求中操作出现的顺序提供。
当编辑工具参数时，请谨慎更改。对原始参数的显著修改可能导致模型重新评估其方法，并可能多次执行工具或采取意外的行动。
配置中断
要使用HITL，在创建智能体时，将中间件添加到智能体的 middleware 列表中。
您通过将工具操作映射到每个操作允许的决策类型来配置它。当工具调用匹配映射中的操作时，中间件将中断执行。
import { createAgent, humanInTheLoopMiddleware } from "langchain";
import { MemorySaver } from "@langchain/langgraph";
const agent = createAgent({
model: "openai:gpt-4o",
tools: [writeFileTool, executeSQLTool, readDataTool],
middleware: [
humanInTheLoopMiddleware({
interruptOn: {
write_file: true, // All decisions (approve, edit, reject) allowed
execute_sql: {
allowedDecisions: ["approve", "reject"],
// No editing allowed
description: "🚨 SQL execution requires DBA approval",
},
// 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
descriptionPrefix: "Tool execution pending approval",
}),
],
// Human-in-the-loop requires checkpointing to handle interrupts.
// In production, use a persistent checkpointer like AsyncPostgresSaver.
checkpointer: new MemorySaver(),
});
您必须配置一个检查点以在中断期间持久化图状态。
在生产环境中，使用持久化检查点，例如 @[AsyncPostgresSaver]。对于测试或原型设计，使用 @[InMemorySaver]。在调用智能体时，传递一个包含 线程 ID 的 config 以将执行与对话线程关联。
有关详细信息，请参阅 LangGraph 中断文档。 响应中断
当您调用智能体时，它会运行直到完成或发生中断。当工具调用与您在 interrupt_on 中配置的策略匹配时，将触发中断。在这种情况下，调用结果将包含一个 __interrupt__ 字段，其中包含需要审查的操作。然后，您可以向审查员展示这些操作，并在提供决策后继续执行。
import { HumanMessage } from "@langchain/core/messages";
import { Command } from "@langchain/langgraph";
// 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).
const config = { configurable: { thread_id: "some_id" } };
// Run the graph until the interrupt is hit.
const result = await agent.invoke(
{
messages: [new HumanMessage("Delete old records from the database")],
},
config
);
// The interrupt contains the full HITL request with action_requests and 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']
// > }
// > ]
// > }
// > )
// > ]
// Resume with approval decision
await agent.invoke(
new Command({
resume: { decisions: [{ type: "approve" }] }, // or "edit", "reject"
}),
config // Same thread ID to resume the paused conversation
);
决策类型
✅ approve
✏️ edit
❌ reject
使用 approve 直接批准工具调用并执行，无需更改。await agent.invoke(
new 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 // Same thread ID to resume the paused conversation
);
使用 edit 在执行前修改工具调用。
提供编辑后的操作，包含新的工具名称和参数。await agent.invoke(
new 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
editedAction: {
// 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 // Same thread ID to resume the paused conversation
);
当编辑工具参数时，请谨慎更改。对原始参数的显著修改可能导致模型重新评估其方法，并可能多次执行工具或采取意外行动。
使用 reject 拒绝工具调用，并提供反馈而不是执行。await agent.invoke(
new 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 // Same thread ID to resume the paused conversation
);
message 添加到对话中，作为反馈以帮助智能体理解为什么该操作被拒绝以及它应该做什么。
多个决策
当多个动作正在审查时，请按照它们在中断中出现的顺序为每个动作提供决策。{
decisions: [
{ type: "approve" },
{
type: "edit",
editedAction: {
name: "tool_name",
args: { param: "new_value" }
}
},
{
type: "reject",
message: "This action is not allowed"
}
]
}
执行生命周期
中间件定义了一个 after_model 钩子，它在模型生成响应之后、任何工具调用执行之前运行：
- 智能体调用模型生成响应。
- 中间件检查响应中的工具调用。
- 如果有任何调用需要人工输入，中间件将使用
HITLRequest、action_requests 和 review_configs 构建一个 HITLRequest 并调用 中断。
- 智能体等待人工决策。
- 根据基于
HITLResponse 的决策，中间件执行批准或编辑的调用，为拒绝的调用合成 @[ToolMessage]，并继续执行。
自定义HITL逻辑
对于更专业的流程，您可以直接使用 中断 原语和 中间件 抽象来构建自定义的 HITL 逻辑。
查看上述的 执行生命周期 以了解如何将中断集成到智能体的操作中。
