Session 11:Human-in-the-Loop——让 Agent 在关键节点等待人工介入
Agent 执行任务时,经常会遇到一些不能完全交给模型自行决定的情况
一、为什么 Agent 需要人工介入
Agent 执行任务时,经常会遇到一些不能完全交给模型自行决定的情况。
以 Research Agent 为例,它需要搜索资料、分析证据、判断资料是否充分,最后生成研究报告。大部分步骤可以自动执行,但如果搜索到的资料互相矛盾、关键证据不足,或者报告中涉及需要确认的重要结论,就可能需要人工介入。
另一个常见场景是 Agent 执行外部操作,例如发送邮件、修改数据库、提交订单、删除文件。即使模型认为自己已经得到了正确的结果,也不代表它有权直接执行这些操作。
因此,Human-in-the-Loop(HITL)是 Agent 工程中的一个重要机制:在预先定义的关键节点暂停自动执行,将当前状态交给人处理,再根据人工反馈继续运行。
这里有两个需要明确的边界:
- 哪些情况需要人工介入,可以由业务规则、程序判断或模型提出建议,但最终的介入策略应该由系统设计决定。
- 人工介入之后,程序需要能够恢复任务,并正确处理人工给出的决定,而不只是把人工输入追加到对话消息里。
二、谁来决定是否需要人工介入
实际项目中,通常会组合使用三种方式。
1. 程序根据明确规则触发
当条件能够明确表达时,优先使用程序判断。
例如:
- 删除文件、发送邮件等高风险操作必须确认。
- 研究报告引用的关键证据不足时,需要审核。
- 数据库更新影响超过一定数量的记录时,需要审批。
- 任务超过自动重试次数后,转交人工处理。
def should_require_approval(action: dict) -> bool:
high_risk_actions = {
"delete_file",
"send_email",
"submit_order",
}
return action["type"] in high_risk_actions
这种方式的好处是规则稳定、可测试,也不依赖模型每次都能正确理解安全要求。
2. LLM 提出人工介入请求
有些情况很难提前写成固定规则。例如,Research Agent 找到了三份资料,其中两份支持某个结论,另一份却提供了相反证据。是否需要人工判断,可能取决于资料内容和研究目标。
此时可以让模型分析当前情况,并输出结构化判断。
from pydantic import BaseModel
from typing import Literal
class ReviewDecision(BaseModel):
needs_review: bool
reason: str
issue_type: Literal[
"insufficient_evidence",
"conflicting_evidence",
"uncertain_conclusion",
"none",
]
程序拿到结果后,可以决定是否暂停工作。
不过,模型输出的 needs_review=False 不应该覆盖程序定义的强制审批规则。对于涉及权限、安全或资金的操作,不能仅靠模型判断是否需要确认。
3. 系统直接设置人工审核节点
还有一些业务天然就需要人工确认。例如,报告正式发布之前必须经过审核。这种情况下,没有必要让 LLM 决定是否审核,直接在工作流中设置审核节点即可。
三种方式可以组合使用:程序处理硬性规则,LLM 识别语义层面的不确定性,工作流保证必须经过的审核步骤不会被跳过。
三、人工介入时,系统需要保存什么
HITL 不只是等待用户输入。一个可以用于生产环境的实现,需要考虑暂停时的任务状态、恢复位置和人工决策。
假设 Research Agent 已经完成资料搜索和初步分析,发现关键证据存在冲突,需要人工判断。
暂停之前,至少需要保留以下信息:
| 信息 | 用途 |
|---|---|
| task_id | 找回对应的研究任务 |
| 当前执行节点 | 知道从哪里恢复 |
| 已搜索的资料 | 避免恢复后重复搜索 |
| 当前分析结果 | 保留已经完成的工作 |
| 待审核内容 | 告诉审核人员需要判断什么 |
| 人工决策结果 | 继续执行时使用 |
| 审核人、时间 | 用于审计和追踪 |
这些数据不一定全部存放在 LangGraph 的 State 中。任务元数据、审核记录、研究资料可以存放在业务数据库中,图的执行状态由 Checkpoint 机制持久化。
需要特别注意:暂停后进程可能已经退出,服务也可能重启。 因此,如果希望任务能够跨进程恢复,就不能只把状态留在内存里。
四、用 LangGraph 实现人工审核
LangGraph 提供了 interrupt() 机制,可以在节点执行过程中暂停图的运行,并向调用方返回等待人工处理的信息。之后,调用方通过 Command(resume=...) 恢复执行。
下面用一个精简的 Research Agent 示例说明核心流程。代码展示了人工审核机制,搜索和分析步骤用固定数据模拟,避免把注意力分散到具体的模型接入上。
4.1 定义状态和节点
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import InMemorySaver
class ResearchState(TypedDict, total=False):
topic: str
evidence: list[str]
analysis: str
review_result: dict
report: str
def search_evidence(state: ResearchState):
# 实际项目中可以调用搜索引擎、RAG 或内部数据库
return {
"evidence": [
"资料 A:支持研究结论",
"资料 B:对研究结论提出相反证据",
]
}
def analyze_evidence(state: ResearchState):
evidence = state["evidence"]
# 示例中用固定判断模拟 LLM 的分析结果
return {
"analysis": (
f"研究主题:{state['topic']}。"
f"共找到 {len(evidence)} 条资料,"
"其中存在相互冲突的证据,需要人工审核。"
)
}
4.2 设置人工审核节点
def human_review(state: ResearchState):
decision = interrupt({
"type": "research_review",
"topic": state["topic"],
"analysis": state["analysis"],
"evidence": state["evidence"],
"question": "证据存在冲突,请选择后续处理方式。",
"options": [
"继续研究并补充证据",
"接受现有证据并生成报告",
"终止任务",
],
})
return {"review_result": decision}
def generate_report(state: ResearchState):
decision = state["review_result"]
if decision["action"] == "terminate":
return {"report": "研究任务已终止。"}
if decision["action"] == "continue_research":
return {"report": "需要返回搜索环节,继续补充证据。"}
return {
"report": (
f"# 研究报告:{state['topic']}\n\n"
f"{state['analysis']}\n\n"
"本报告根据人工审核决定生成。"
)
}
这里的 interrupt() 会暂停当前图的执行,将审核所需的信息交给调用方。人工提交的内容会作为恢复值返回给这个节点。
示例为了突出机制,把“继续研究”暂时返回成一条状态信息。真正的项目中,应该将它设计成图的条件分支,让任务返回搜索节点继续执行,而不是把提示文字当成已经完成的操作。
4.3 构建工作流并启用 Checkpoint
builder = StateGraph(ResearchState)
builder.add_node("search", search_evidence)
builder.add_node("analyze", analyze_evidence)
builder.add_node("review", human_review)
builder.add_node("report", generate_report)
builder.add_edge(START, "search")
builder.add_edge("search", "analyze")
builder.add_edge("analyze", "review")
builder.add_edge("review", "report")
builder.add_edge("report", END)
graph = builder.compile(
checkpointer=InMemorySaver()
)
这里使用 InMemorySaver 只是为了演示。服务重启后,内存里的 Checkpoint 就会丢失;生产环境需要使用适合部署环境的持久化 Checkpointer。
4.4 启动任务,等待人工处理
config = {
"configurable": {
"thread_id": "research-task-001"
}
}
result = graph.invoke(
{
"topic": "某项 AI 技术的实际应用情况"
},
config=config,
)
print(result)
当执行到 interrupt() 时,图会暂停。调用方可以检查返回结果中的中断信息,将研究主题、分析结果和待审核问题展示在管理页面中。
实际 API 层还需要识别图是否处于中断状态,并将任务标记为等待审核。不能把暂停误认为执行成功。
4.5 人工提交决定,恢复任务
假设审核人员确认接受当前证据:
result = graph.invoke(
Command(
resume={
"action": "accept_evidence",
"reviewer": "reviewer-001",
"comment": "已检查现有证据,同意生成报告。",
}
),
config=config,
)
print(result)
LangGraph 会从保存的执行状态恢复,并将人工提交的决定返回给 human_review 节点。该节点返回 review_result 后,图才会继续执行报告生成节点。
这里有几个实现细节需要注意:
- 恢复时必须使用相同的
thread_id。 它用于定位对应任务的 Checkpoint。生产系统还应该在业务数据库中维护自己的任务 ID,并将两者关联起来。 interrupt()所在节点可能重新执行。 因此,在调用interrupt()之前,不要放置不可重复的外部副作用,例如直接扣款或发送邮件。- 恢复值需要校验。 人工提交的数据也可能格式错误、缺少字段,或者包含不允许的操作。应通过 Pydantic 等机制进行结构校验,并由程序检查权限和业务规则。
- 人工操作必须有身份和权限控制。 不能允许任何知道
thread_id的调用方直接批准任务。
五、生产环境中的 HITL 还需要处理什么
上面的代码只展示了图的暂停与恢复。要让它在真实业务中稳定运行,还需要补齐任务管理和审核机制。
5.1 人工审核需要独立的任务状态
可以在业务数据库中维护类似这样的状态:
RUNNING
|
v
WAITING_FOR_REVIEW
|
+----> APPROVED
|
+----> REJECTED
|
+----> NEED_MORE_EVIDENCE
这里的 WAITING_FOR_REVIEW 表示图已经暂停,等待审核人员处理。审核人员提交决定后,程序需要校验任务状态,再触发恢复。
状态检查很重要。如果两名审核人员同时提交决定,或者客户端因网络超时重复提交,系统不能让同一个任务被重复恢复。
5.2 人工审核可能等待很长时间
任务可能几分钟后就有人处理,也可能数天没有人处理。因此,暂停期间不应该一直占用一个 Web 请求或工作线程。
比较常见的实现方式是:
- API 启动任务后,由后台 Worker 执行 Agent。
- Agent 遇到
interrupt()后,保存任务状态并结束当前执行。 - 审核页面从数据库查询等待审核的任务。
- 人工提交决定后,API 校验权限和任务状态,将恢复任务放入队列。
- Worker 重新加载 Checkpoint,继续执行图。
队列中的恢复任务也需要考虑重复投递、Worker 崩溃和处理失败。通常会使用任务状态、幂等键和有限重试来避免重复执行。
5.3 人工审核不能代替程序校验
人工选择“批准”只代表审核流程已经通过,不代表输入一定满足程序要求。
例如,审核人员批准了一份报告,程序仍然需要检查报告格式、必填字段和数据完整性。如果批准操作涉及高风险外部副作用,还需要在执行时再次验证权限和业务条件。
对于高风险操作,审批记录最好包含被批准的具体内容或内容版本。否则,审核人员批准之后,如果待执行内容又发生变化,就可能出现“批准的是 A,实际执行的是 B”的问题。
5.4 超时和无人审核
如果任务长时间无人处理,需要有明确的业务策略:
- 超过一定时间提醒审核人员。
- 将任务转交给其他审核人员。
- 超过截止时间后取消任务。
- 对允许自动处理的低风险场景,按预先定义的规则继续执行。
不要把超时后自动批准作为通用默认行为。是否允许自动通过,应由具体业务风险决定。
六、HITL 和普通的 LLM 对话有什么区别
普通的 LLM 对话中,用户发送一条消息,模型生成回答,整个过程通常由一次请求驱动。
HITL 处理的是一个正在执行的任务。任务可能已经调用过多个工具、积累了大量状态,并且已经执行了部分业务操作。人工反馈进入系统之后,程序需要恢复原有任务的执行进度,而不是重新从头生成一段回答。
这也是为什么 HITL 通常需要与工作流、状态持久化和任务调度一起设计。
在 LangGraph 中,interrupt() 负责暂停,Command(resume=...) 负责恢复,Checkpointer 负责保存和读取图的执行状态。业务数据库负责记录审核任务、审核人、审核决定以及任务生命周期;API 和后台 Worker 负责把这些机制连接起来。
七、总结
HITL 的核心是将人工判断纳入 Agent 的执行流程。程序负责确定强制审核规则、权限和状态转换,LLM 可以识别需要关注的不确定性,人工负责处理系统无法安全自动决策的事项。
LangGraph 提供了比较直接的暂停与恢复机制,但它不会自动解决审核权限、并发提交、任务超时、重复执行和业务审计等问题。这些仍然需要结合具体业务进行设计。
希望这篇文章能对你有所帮助。关注我,持续分享更多实用、好用的 AI 干货。