LangGraph 修复子图消息流，AI 助手可显示子任务过程

2026 年 11 月 14 日，LangGraph 发布 Python 1.2.22，修复了子图带独立配置运行时，消息和工具事件无法传回部分调用方的问题。用它构建多步骤 AI 助手的开发者，如果遇到子任务正在执行、界面却迟迟没有过程输出的情况，值得检查这次更新。本文说明修复的触发条件、流式订阅配置，以及前端接收事件后需要核对的来源信息。官方发布记录

[配图建议：两个子任务终端把消息片段传向同一个屏幕 + 克制的三维科技概念插画]

子任务在工作，主界面如何收到过程

设想一个企业文档助手。主流程收到问题后，把资料查询交给一个子图，子图调用工具、阅读结果，再组织回答。产品希望用户逐步看到“查询开始”“查询完成”和生成中的文字，由此判断任务进展。这些提示需要从执行端送到主流程订阅的事件流，再由应用转换成界面内容。

修复 PR #9698 说明，自 1.2.19 的相关改动后，图在调用节点内部使用自己的 thread_id、checkpoint_ns、checkpoint_id，或带自己 configurable 的 runnable 运行时，继承的消息与工具流处理器会被过滤。这个处理也影响了已经启用 subgraphs=True 的调用方，导致它收不到原本希望订阅的子图事件。官方修复说明

因此，排查入口可以放在“子图怎样被调用”上。尤其要查看调用时传入了什么配置，以及父流程订阅了哪些事件。官方回归用例覆盖了子图显式传入自己的会话 ID，以及显式传入与父流程相同 ID 的情况。显式调用配置与子图订阅方式需要一起检查。这两种配置都应纳入项目的检查范围。固定版本回归用例

本次 PR 于北京时间 11 月 14 日 08:58 合并，1.2.22 于当日 09:43 发布。版本发布是本文采用的更新日期，项目实际升级和上线的时间由各自部署流程决定。本文核查对象为 Python 包及其同步、异步实现。PR 合并记录 正式版本记录

[配图建议：文档助手主流程与资料查询子图之间的消息传递路径 + 简洁流程示意图]

打开子图订阅，还要识别事件来源

subgraphs=True 是这次修复中的关键条件。代码现在根据处理器是否订阅子图来决定过滤范围，使订阅子图的调用方继续获得相应消息和工具事件。同步 stream 与异步 astream 两条实现均包含此次调整。1.2.22 实现代码

这里的 thread_id 属于运行配置。在使用检查点保存器的场景中，它用于定位一个线程下的状态和检查点，让应用能够恢复、继续会话。业务上把多个阶段拆成独立子任务后，状态保存与过程展示会分别涉及配置和订阅，二者需要共同设计。官方持久化文档

事件恢复传递之后，消费端还需要正确理解命名空间。PR 明确保留子图原来的 namespace，独立运行子图的顶层节点可能仍带空元组 ()。官方用例也用这个形态检查工具开始、工具完成与消息片段。因此，前端如果仅凭“命名空间是否包含父节点名”来分配展示区域，就需要重新检查这条映射规则。官方修复说明与事件断言 回归用例

界面展示应同时核对事件类型、命名空间和业务任务标识。例如，两个资料查询子任务同时运行时，应用可以在自己的任务记录中保存它们与界面区域的对应关系，再根据实际收到的事件填充进度。这个做法是应用层设计建议，具体映射需要结合项目现有协议验证。

[配图建议：事件类型、命名空间与业务任务记录在消费端汇合 + 技术编辑风格的结构图]

先看收到什么，再接进聊天界面

下面是消费端片段，假设项目已经构建好 parent_graph，并准备了 inputs 和 config。它沿用官方回归用例中的订阅参数，先打印事件结构，方便开发者核对传递链路。

for part in parent_graph.stream(
    inputs,
    config,
    stream_mode=["messages", "tools"],
    subgraphs=True,
    version="v2",
):
    print(part["type"], part["ns"], part["data"])

version="v2" 使用统一的流式事件外层结构，其中 type 表示事件类型，ns 表示命名空间，data 承载对应负载。这种结构从 1.1 起即可使用。官方文档说明，messages 模式的负载包含消息片段及元数据。tools 模式及其开始、完成事件则可在本次固定版本用例中核对。官方流式文档 1.2.22 回归用例

接进真实产品时，可以先用一个容易识别的短问题跑完一次查询，把原始事件按接收顺序记录下来，再逐项对应界面上的提示。消息片段、工具状态和最终回答分别按自己的语义处理。如果产品还展示自定义业务进度，则继续按项目已有的自定义事件协议处理，逐个核对来源与显示位置。

异步服务可以用 astream 消费同类事件。官方为同步与异步调用分别增加了回归用例，这给后端采用不同执行方式的团队提供了可对照的检查入口。项目仍需以自己的模型、工具和并发任务验证完整链路。同步与异步回归用例

[配图建议：原始事件记录与聊天界面进度逐项对应 + 清晰的开发工作台示意图]

升级时，把配置和展示一起验收

最适合优先评估这次更新的，是使用 Python LangGraph、在节点内调用带显式配置子图、并向用户展示子任务过程的团队。可以先查看部署环境中的包版本和依赖锁文件，在测试环境升级到 1.2.22，再选一条真实工作流验证。

还应记录事件数量和显示顺序。恢复子图输出后，原有界面可能接收到更多过程信息，前端需要决定哪些内容进入用户可见区域，哪些保存在开发日志中。含工具参数或业务资料的事件，应遵循项目现有的数据展示规则。这些是接入事件流时的实际产品成本。

这次更新带来的直接收益是恢复特定调用方式下的过程可见性。检索耗时、模型回答质量和部署资源占用，需要由对应工作负载分别测量。官方修复证据来自处理器过滤逻辑及回归用例，读者可以据此确定自己的验证目标，再安排升级节奏。官方修复 PR

[配图建议：开发者核对调用配置、事件日志和最终界面 + 真实感技术工作场景插画]

今天先检查一条子图调用

今天可以先打开项目里一条带显式配置的子图调用，确认部署版本、父流程的 subgraphs 设置，以及消息和工具事件的消费路径。若正好命中这次修复场景，就在测试环境记录一次升级前后的事件序列，把过程提示与最终回答一起验收。

你更希望 AI 助手展示工具执行状态，还是逐步生成的回答？这个选择会直接影响产品订阅哪些事件、如何组织界面。

核查时间为 2026 年 11 月 15 日，北京时间。本文依据官方发布记录、修复 PR、固定版本源码和回归用例及官方文档进行核查，场景与接入建议用于说明应用方法，封面为原创 AI 概念插画。

[配图建议：一条子图调用与完整事件记录并排呈现 + 留白充足的技术笔记插画]