👁 104 次阅读

HumanInTheLoopMiddleware 配合 ainvoke 调用报错如何排查

来源链接：https://github.com/langchain-ai/langchain/issues/34974 LangChain 的 HumanInTheLoopMiddleware 在设计上允许开发者在 Agent 的工具调用链中插入人工审批节点，实现”人在回路”的决策控制。然而在实际开发中，当 Agent 以 .ainvoke() 异步方式被调用时，该 Middleware 会抛出未预期的错误，导致整个 Agent 执行中断。该问题对应 langchain-ai/langchain 的 Issue #34974，标签包含 bug、core、langchain、external，当前状态为 open，官方尚未合入统一修复方案。据 issue 讨论，该问题创建于 2026-02-02，截至 2026-08-17 共积累 26 条评论，社区至今未给出确切的合并 PR。

现象描述

开发者在使用 create_agent 构建 Agent 时，配置了 HumanInTheLoopMiddleware 并指定了 interrupt_on 规则，但在以 .ainvoke() 异步调用 Agent 时触发运行时错误。典型配置如下：

agent = create_agent(
    model="gpt-4.1",
    tools=[write_file_tool, execute_sql_tool, read_data_tool],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "write_file": True,
                "execute_sql": {"allowed_decisions": ["approve", "reject"]},
            }
        )
    ],
)
result = await agent.ainvoke(query, config={"configurable": {"thread_id": session_id}})

据 issue 讨论，报调用者反馈的错误与 checkpointer 配置相关——无论使用 InMemorySaver 还是切换为 AsyncPostgresSaver，错误均依然存在。

背景原因

据 issue 讨论，该问题的根本原因尚未被官方确认。社区排查过程中发现了若干潜在关联因素： 异步调用路径的兼容性问题：.ainvoke() 走的是异步调用路径，而 HumanInTheLoopMiddleware 的 interrupt_on 机制在该路径下可能存在状态同步缺陷。当 Agent 需要暂停等待人工决策时，中间件内部的状态管理与异步执行上下文之间可能发生冲突。 Python 版本差异：据 issue 讨论，提问者使用 Python 3.10，而社区回复者在 Python 3.11.11 环境下使用相同代码片段无法复现错误。这一差异提示底层异步运行时行为可能存在版本相关的差异。 Checkpointer 交互：HumanInTheLoopMiddleware 依赖于 checkpointer 持久化 Agent 的中间状态，以便在人工决策后恢复执行。据 issue 讨论，即使用户切换到 AsyncPostgresSaver 并正确传入 config，问题仍未解决，说明 checkpointer 本身并非唯一触发因素。 FastAPI 环境交互：据 issue 讨论，提问者的初始代码涉及通过 FastAPI 服务接收请求后直接运行 Agent。社区建议脱离 FastAPI 环境验证是否能复现，但该验证过程在讨论中尚未给出最终结论。

排查或量化方法

定位此类问题需系统性地隔离变量，以下是基于 issue 讨论中社区建议的排查步骤： 1. 脱离 FastAPI 环境验证：将 Agent 的创建与调用放入独立脚本中直接执行，排除 HTTP 框架层的异步上下文干扰。 2. 切换 Checkpointer：将 InMemorySaver 替换为 AsyncPostgresSaver，观察错误是否变化。据 issue 讨论，提问者已执行此步骤，结果未改变。 3. 对比 Python 版本：将运行环境从 Python 3.10 升级至 3.11.x，验证是否为版本相关缺陷。据 issue 讨论，社区回复者在 3.11.11 下无法复现。 4. 移除 Middleware 隔离验证：暂时移除 HumanInTheLoopMiddleware，确认 .ainvoke() 本身无问题，再逐步加入 Middleware 观察错误出现时机。 5. 对比 .invoke() 与 .ainvoke()：将调用方式从 .ainvoke() 改为同步的 .invoke()，确认是否仅在异步路径下触发错误。

完整解决方案

该 Issue 当前状态为 open，官方尚未合入统一修复方案。据 issue 讨论，社区目前提出的临时规避方案包括： 方案一：升级 Python 版本 据 issue 讨论，Python 3.11+ 环境下暂未复现该错误。如果开发环境允许，将 Python 升级至 3.11 及以上版本是当前最直接的规避手段。 方案二：改用同步调用路径 将 .ainvoke() 替换为 .invoke()，绕过异步调用路径：

# 替代方案：使用同步调用
result = agent.invoke(query, config={"configurable": {"thread_id": session_id}})

此方案在需要异步 I/O 的场景中会造成阻塞，适用于对延迟要求不高的批处理场景。 方案三：调整 Middleware 配置粒度 据 issue 讨论，interrupt_on 的配置粒度可能影响触发时机。尝试将全部工具设为统一策略而非混合配置：

agent = create_agent(
    model="gpt-4.1",
    tools=[write_file_tool, execute_sql_tool, read_data_tool],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "write_file": {"allowed_decisions": ["approve", "reject"]},
                "execute_sql": {"allowed_decisions": ["approve", "reject"]},
            }
        )
    ],
)

方案四：等待官方修复 鉴于该 Issue 自 2026-02-02 创建至今仍未关闭，且累计 26 条评论讨论，建议开发者在 langchain 版本发布说明中关注是否包含对 HumanInTheLoopMiddleware 异步路径的修复。

参数或对比表格

对比维度	.invoke() 同步调用	.ainvoke() 异步调用
HumanInTheLoopMiddleware 兼容性	据 issue 讨论，未报告异常	据 issue 讨论，报错
Python 3.10 环境	据 issue 讨论，未报告异常	据 issue 讨论，报错
Python 3.11 环境	据 issue 讨论，未报告异常	据 issue 讨论，未复现
适用场景	批处理、低延迟要求场景	高并发、异步 I/O 密集场景
阻塞行为	同步阻塞	非阻塞（但报错后行为异常）
FastAPI 集成	需 run_in_executor 包装	原生支持
Checkpointer 类型	持久化方式	据 issue 讨论的测试结果
InMemorySaver	内存存储	报错
AsyncPostgresSaver	PostgreSQL 持久化	报错（提问者已验证）

常见错误排查

1. 未传入 config 参数：调用 .ainvoke() 时若未传入包含 thread_id 的 config，HumanInTheLoopMiddleware 无法定位持久化状态，导致执行异常。确保调用时包含 config={"configurable": {"thread_id": session_id}}。 2. Python 版本不兼容：据 issue 讨论，Python 3.10 环境下可稳定复现，3.11+ 环境暂未复现。开发者应优先检查 Python 版本。 3. interrupt_on 配置格式错误：据 issue 正文示例，interrupt_on 的值可以是布尔值（如 True 表示全部决策）或字典（指定 allowed_decisions）。混用不同格式可能导致状态初始化不一致。 4. Middleware 列表顺序问题：据 issue 讨论，当 HumanInTheLoopMiddleware 与其他 Middleware 共存时，其插入位置可能影响异步状态流转。建议将其放置在 Middleware 列表的首位。 5. FastAPI 异步上下文冲突：据 issue 讨论，通过 FastAPI 接收请求后直接在 async 视图中创建并调用 Agent，可能与 FastAPI 的异步事件循环产生上下文冲突。建议将 Agent 创建逻辑与 HTTP 请求处理分离。

实践建议

架构层面：在生产环境中使用 HumanInTheLoopMiddleware 时，不建议依赖 InMemorySaver，应使用 AsyncPostgresSaver 等持久化 checkpointer，以确保人工决策后状态可恢复。据 issue 讨论，这一建议同样适用于异步调用场景。 版本锁定：在 LangChain 官方修复该 Issue 之前，建议在 pyproject.toml 或 requirements.txt 中锁定已知可用的 Python 版本与 langchain 包版本，避免因自动升级引入不可预期的行为变化。 降级策略：对于线上服务，可设计降级逻辑——检测到 HumanInTheLoopMiddleware 异步调用异常时，自动切换为同步调用路径或跳过人工审批节点（仅在风险可控的审批项上）。 回归测试：据 issue 讨论，该错误在不同环境下表现不一致，建议在 CI/CD 流程中加入针对 HumanInTheLoopMiddleware + .ainvoke() 组合的回归测试用例，覆盖 Python 3.10 和 3.11 两个版本。 跟踪上游进展：该 Issue 当前状态为 open，社区已有 26 条评论讨论但尚未产生合并 PR。开发者应定期查看该 Issue 的更新，一旦官方发布包含修复的版本，及时升级并移除临时规避代码。

FAQ

Q1：HumanInTheLoopMiddleware 是否官方支持 .ainvoke() 调用？ 据 issue 讨论，该问题被标记为 bug，说明理论上应支持 .ainvoke() 但实际存在缺陷。该 Issue 当前状态为 open，官方尚未合入统一修复方案。 Q2：该问题是否在 langchain-core 层还是 langchain 层？ 据 Issue 标签，涉及 langchain 和 langchain-core 两个包。HumanInTheLoopMiddleware 的实现横跨 Agent 层和核心中间件层，具体出错位置需结合完整堆栈信息判断。 Q3：使用 AsyncPostgresSaver 是否一定能解决问题？ 据 issue 讨论，提问者已验证将 InMemorySaver 替换为 AsyncPostgresSaver 后错误依然存在，因此 checkpointer 类型并非唯一触发因素。 Q4：该 Issue 是否有已知的合并 PR？ 据 issue 讨论，截至 2026-08-17 最后更新，该 Issue 状态仍为 open，共 26 条评论，未记录已合并的 PR。该功能的具体实现修复尚未公开。 Q5：生产环境中如何安全使用 HumanInTheLoopMiddleware？ 在当前版本存在已知缺陷的情况下，建议：升级 Python 至 3.11+、使用持久化 checkpointer、设计降级调用策略、在 CI 中加入回归测试，并持续关注 Issue #34974 的后续更新。