Session 11:Human-in-the-Loop——让 Agent 在关键节点等待人工介入

Agent 执行任务时,经常会遇到一些不能完全交给模型自行决定的情况

一、为什么 Agent 需要人工介入

Agent 执行任务时,经常会遇到一些不能完全交给模型自行决定的情况。

以 Research Agent 为例,它需要搜索资料、分析证据、判断资料是否充分,最后生成研究报告。大部分步骤可以自动执行,但如果搜索到的资料互相矛盾、关键证据不足,或者报告中涉及需要确认的重要结论,就可能需要人工介入。

另一个常见场景是 Agent 执行外部操作,例如发送邮件、修改数据库、提交订单、删除文件。即使模型认为自己已经得到了正确的结果,也不代表它有权直接执行这些操作。

因此,Human-in-the-Loop(HITL)是 Agent 工程中的一个重要机制:在预先定义的关键节点暂停自动执行,将当前状态交给人处理,再根据人工反馈继续运行。

这里有两个需要明确的边界:

  • 哪些情况需要人工介入,可以由业务规则、程序判断或模型提出建议,但最终的介入策略应该由系统设计决定。
  • 人工介入之后,程序需要能够恢复任务,并正确处理人工给出的决定,而不只是把人工输入追加到对话消息里。

二、谁来决定是否需要人工介入

实际项目中,通常会组合使用三种方式。

1. 程序根据明确规则触发

当条件能够明确表达时,优先使用程序判断。

例如:

  • 删除文件、发送邮件等高风险操作必须确认。
  • 研究报告引用的关键证据不足时,需要审核。
  • 数据库更新影响超过一定数量的记录时,需要审批。
  • 任务超过自动重试次数后,转交人工处理。
text
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 找到了三份资料,其中两份支持某个结论,另一份却提供了相反证据。是否需要人工判断,可能取决于资料内容和研究目标。

此时可以让模型分析当前情况,并输出结构化判断。

text
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 定义状态和节点

text
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 设置人工审核节点

text
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

text
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 启动任务,等待人工处理

text
config = {
    "configurable": {
        "thread_id": "research-task-001"
    }
}

result = graph.invoke(
    {
        "topic": "某项 AI 技术的实际应用情况"
    },
    config=config,
)

print(result)

当执行到 interrupt() 时,图会暂停。调用方可以检查返回结果中的中断信息,将研究主题、分析结果和待审核问题展示在管理页面中。

实际 API 层还需要识别图是否处于中断状态,并将任务标记为等待审核。不能把暂停误认为执行成功。

4.5 人工提交决定,恢复任务

假设审核人员确认接受当前证据:

text
result = graph.invoke(
    Command(
        resume={
            "action": "accept_evidence",
            "reviewer": "reviewer-001",
            "comment": "已检查现有证据,同意生成报告。",
        }
    ),
    config=config,
)

print(result)

LangGraph 会从保存的执行状态恢复,并将人工提交的决定返回给 human_review 节点。该节点返回 review_result 后,图才会继续执行报告生成节点。

这里有几个实现细节需要注意:

  1. 恢复时必须使用相同的thread_id。 它用于定位对应任务的 Checkpoint。生产系统还应该在业务数据库中维护自己的任务 ID,并将两者关联起来。
  2. interrupt()所在节点可能重新执行。 因此,在调用 interrupt() 之前,不要放置不可重复的外部副作用,例如直接扣款或发送邮件。
  3. 恢复值需要校验。 人工提交的数据也可能格式错误、缺少字段,或者包含不允许的操作。应通过 Pydantic 等机制进行结构校验,并由程序检查权限和业务规则。
  4. 人工操作必须有身份和权限控制。 不能允许任何知道 thread_id 的调用方直接批准任务。

五、生产环境中的 HITL 还需要处理什么

上面的代码只展示了图的暂停与恢复。要让它在真实业务中稳定运行,还需要补齐任务管理和审核机制。

5.1 人工审核需要独立的任务状态

可以在业务数据库中维护类似这样的状态:

text
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 干货。

本文目录