Skip to main content

Human-in-the-loop

心智模型​

Human-in-the-loop (HITL) 中间件在 Agent 的工具调用前设置了一道审批闸门。当模型准备执行敏感操作时，它通过 LangGraph 的 interrupt 机制暂停执行，将决定权交给人类，并根据审批、修改、拒绝或直接回复等决策来恢复执行。整个过程由内置中间件自动化，开发者只需配置哪些工具需要审批以及允许的决策类型。

二级标题及内容​

  • 【决策类型】Interrupt decision types 定义了四种人类响应中断的决策：

    • ✅ approve：批准并按原样执行。
    • ✏️ edit：修改参数后执行。注意：大幅修改可能导致模型重新评估并多次执行工具或采取意外行动。
    • ❌ reject：拒绝并附带反馈说明，反馈会添加到对话中。
    • 💬 respond：跳过工具执行，直接以人类回复作为工具结果，适用于 ask_user 类工具。

  • 【配置中断】Configuring interrupts 将 HumanInTheLoopMiddleware 加入 middleware 列表，通过 interrupt_on 配置需要审批的工具名及允许的决策类型。必须配置 checkpointer 来跨中断持久化状态。

  • 【响应中断】Responding to interrupts 用 version="v2" 调用 agent.invoke，遇中断时返回 GraphOutput 中断列表。恢复时传递 Command(resume={"decisions": [...]})，决策列表需与中断顺序一致。

  • 【流式传输】Streaming with human-in-the-loop 使用 stream() 替代 invoke() 获取实时更新，在 version="v2" 下通过 stream_mode=["updates", "messages"] 同时监听模型 Token 和中断状态。

  • 【执行生命周期】Execution lifecycle

    1. 模型生成响应 → 2. 中间件检查工具调用 → 3. 需审批时触发中断 → 4. 等待人类决策 → 5. 依据决策执行/反馈/直接回复并恢复。

  • 【自定义逻辑】Custom HITL logic 对于专业工作流，可直接使用 interrupt 和中间件抽象构建自定义逻辑。

最佳实践​

  • 必须配置持久化：使用 checkpointer（生产环境用 AsyncPostgresSaver，测试用 InMemorySaver）来保证暂停期间状态可恢复。调用时需传入含 thread_id 的 config。
  • 审慎使用编辑：编辑参数时尽量保守，避免因大幅修改导致模型行为异常。
  • 决策顺序一致：当多个操作同时暂停时，提供的决策列表顺序必须与中断列表顺序一致。

Human-in-the-loop (HITL) 的核心价值是在关键决策点引入人工判断。使用场景集中在以下五类：

1. 合规与安全审批

监管要求或安全策略要求某些操作必须有人类确认。

  • 金融合规：交易金额超阈值或涉及敏感账户时，必须分析师审批才执行转账
  • 医疗安全：AI 生成处方或诊疗建议后，需医生确认后才发送给患者
  • 法律合规：生成正式合同或法律文件前，需律师审核

2. 高风险写操作

涉及数据修改、删除或外部通信的操作。

  • 数据库操作：DELETE 或 UPDATE 语句，尤其是影响大量行时
  • 文件系统：删除文件、修改生产配置
  • 对外通信：发送邮件、短信、Slack 通知前需确认内容

3. 内容质量把关

AI 生成的内容需要人类审查。

  • 对外发布：社交媒体帖子、新闻稿等对外内容
  • 客户沟通：客服 Agent 生成给客户的回复，需确认语气和准确性
  • 敏感回复：涉及投诉处理、退款承诺等可能产生法律后果的回复

4. 澄清与补充信息

Agent 需要向用户确认或补充信息。

  • 歧义消解：用户说"取消订单"但有多笔订单时，Agent 暂停请用户指定
  • 信息补充：Agent 需要用户偏好但未提供时（ask_user 工具 + respond 决策）
  • 确认步骤：多步骤操作中，在不可逆步骤前请用户确认

5. 分阶段工作流

将复杂任务拆分为多个人工检查点。

  • 代码审查：Agent 生成代码 → 人工审查 → 批准后提交 PR
  • 内容创作：Agent 写初稿 → 人工审批/编辑 → Agent 继续润色 → 最终审批
  • 数据管道：Agent 处理数据 → 人工验证结果 → Agent 写入生产库

与 Guardrails 的区别：Guardrails 是自动规则（关键词拦截、PII 脱敏）；HITL 是人工决策，用于规则无法自动判断的场景。两者通常组合：先用 Guardrails 自动过滤，敏感操作再进入 HITL 审批。