流断后 LangGraph 如何避免漏事件

核心结论

LangGraph Python SDK 的流断线处理要分成两件事：重连让客户端继续收到新事件，Last-Event-ID 游标才让服务器知道从哪里补发。没有游标时，连接恢复并不等于事件无缝恢复。LangGraph SDK 在 2026 年 10 月 28 日合并的改动，开始对无游标的重连发出警告，但仍然继续连接；对于开发者，这意味着不能只看流有没有重新出数据，还要把可恢复性配置和告警纳入运行时检查。

这一区分在长时间运行的 Agent 特别重要：用户界面看到“还在生成”，并不证明断线期间的工具调用、状态更新或文本片段都已补齐。应用若把收到的片段当作完整执行记录，可能出现界面状态、持久化记录与服务端运行状态不一致。以下讨论的是 LangGraph Python SDK 的 SSE 客户端重连，不代表所有 SSE 客户端或其他 LangGraph SDK 的行为。

重连和恢复不是一回事

服务端发送事件流时，可以为事件附上 id。客户端记录最近处理到的事件标识，重连时通过 Last-Event-ID 请求续接。服务器是否能依据该标识重放事件，还取决于运行是否启用了可恢复流以及服务端保留事件的能力。LangGraph 的 stream_resumable 参数是这条恢复链路中的关键配置；但只要客户端没有游标，服务器就无法知道该从哪个位置继续补发。

LangGraph 仓库在 10 月 28 日合并的 PR #9482 明确处理了这一边界：当流断开后 SDK 发起重连，如果请求没有 Last-Event-ID，就发出警告；警告覆盖两种来源——流本身还没有产生可用事件标识，或调用方提供的请求头里也没有游标。SDK 不会因缺少游标而拒绝重连，因为拒绝会让客户端连断线之后的事件也收不到。这个行为是“明确告知可能有缺口，同时尽量恢复后续接收”，而不是“自动补齐此前丢失的部分”。

为什么不能把重连成功当作恢复成功？假设事件 A 已抵达客户端，之后连接中断，服务端又发出事件 B 和 C，而客户端没有记录 A 对应的游标。新的连接可以继续收到 D、E，但服务器无法从请求中确定 B、C 应否重放、从何处重放。结果是连接仍然可用，事件序列却可能有空洞。PR 的说明特别指出，没有游标时无法重放断线期间已发送的内容；这是协议状态缺失，不是简单的网络重试次数不足。

两项修复分别解决什么

相邻的 PR #9477 修正了 Python SDK 的 SSE 解析与游标状态处理。改动包括保留跨数据块的解码游标、处理空数据行与未命名的空事件、及时发出以回车结尾的行，并让游标在重连后继续存在。它的目标是避免客户端解析事件流时丢掉合法内容，或在连接恢复时忘记已读位置。PR 同时明确限定：它并未声称穷尽符合 SSE 规范的所有情况，Python 与 JavaScript 对 JSON 的具体解释仍可能有语言差异。

PR #9481 处理的是另一条路径：runs.wait、runs.join 与 runs.cancel(wait=True) 在响应中断后需要重新请求时，过去的重连请求没有退避，429、5xx 或连接拒绝可能立刻使调用失败，掉线后也可能立即反复重连。该改动让这些等待型调用采用与流路径相同的退避思路，并在限定次数内重试相关失败；首次请求失败和其他状态码仍按原有错误路径处理。它改善的是重连失败时的恢复策略，不会自动补上没有游标的事件。

因此排查“重连后内容不完整”时，至少要区分三类问题：事件帧解码错误、没有可用游标，以及重连请求本身遭遇临时 HTTP 或网络错误。解析器修正解决第一类，游标与可恢复流配置解决第二类，带退避的重试解决第三类。把这三类都叫作“网络不稳定”，会让重试参数成为万能药，反而掩盖真正的数据完整性风险。

需要留意版本边界：LangGraph SDK 0.4.10 于 2026 年 10 月 26 日发布，其官方发布记录列出了 Python SDK 对多行 SSE 数据、空 ID 和开头 BOM 的规范处理，以及 stream_resumable 参数在 runs 重载中的支持。本文提到的无游标告警和 wait/join/cancel 重连退避，则来自 10 月 28 日合并的 PR；查阅时最新发布标签仍为 0.4.10，不能把这些后续主分支改动误说成该已发布版本已经包含。升级或部署前应核对实际安装包版本与变更是否进入发行版。

在应用里建立完整性边界

首先，确认创建运行时是否按需要启用 stream_resumable，并使用与之匹配的 SDK 版本。LangGraph 的官方流式运行文档说明了流式运行的客户端接口；Python SDK 的参数与类型细节也可以从 langgraph-sdk 发布页及仓库发行记录核对。不要只在客户端打开“自动重连”就认为事件可恢复：要确认服务端运行提供恢复能力，并且客户端实际发出了有效的 Last-Event-ID。

其次，把“连接状态”和“事件连续性”分开呈现。连接重建后，可以显示正在继续接收，但在收到可验证的游标之前，不应向上层承诺中间内容完整。对有副作用的工具事件，不要仅凭 UI 片段进行重复执行；应使用运行 ID、事件游标或业务幂等键去重，并在最终完成后从服务端状态核对结果。游标能描述进度，却不等于应用侧副作用已经恰好执行一次，二者需要各自设计。

第三，把无游标警告转成可观测性信号。记录运行 ID、重连次数、最后一个事件 ID 是否存在、请求状态码和最终运行状态；日志中避免写入敏感的完整事件负载。发生警告时，检查运行是否启用可恢复流、断线是否发生在首个带 ID 的事件之前，以及代理或自定义客户端是否剥离了 Last-Event-ID。如果请求经过网关，也应检查它是否保留该请求头，并让流式响应不被缓冲成普通响应；这是根据协议头的用途得出的排查方向，不是上述 PR 声称已修复网关行为。

第四，做故障注入测试，不要只测正常完成。构造一个会在事件中途断开的测试流，分别覆盖：断开前从未收到 ID、已有 ID 后断开、服务端返回 502 后再次重连，以及连续多次重连。断言每次请求的 Last-Event-ID 是否等于最近已消费事件，并检查恢复后事件是否有重复或缺口。PR #9483 的测试专门检查连续重连时游标是否推进到最新事件，也覆盖重连过程中出现 502 的情况；可以借鉴其测试意图，而不是把只检查“最终收到一些数据”当成完整性测试。

对于同步与异步客户端，都应分别验证告警和重连行为。PR #9482 的测试分别覆盖两种调用路径，并用有无流游标、调用者自带游标的情况区分是否应告警。应用封装 SDK 时也要确保日志和指标不会因为只覆盖同步调用而漏掉异步路径。

版本核对与排障顺序

排障可以按事件生命周期从前往后检查。先看 SDK 版本和发行说明，确认是否具有 0.4.10 中发布的 SSE 解析器修正；再看运行参数是否启用可恢复流；接着检查断线前是否收到事件 ID、重连请求里是否真的携带 Last-Event-ID；最后才分析 429、5xx、连接拒绝等重连失败和退避行为。这个顺序能把数据缺口与连接失败拆开，避免把“重连后继续有事件”当成断线期间的事件已补回。

还要核对部署中的实际依赖，而不只是本地锁文件。容器镜像、服务进程和异步 worker 可能分别加载不同环境或版本；至少在启动日志或诊断端点中记录 langgraph-sdk 版本，并在版本变更后跑中断恢复测试。10 月 28 日合并的 PR 是仓库变更记录，不是发行版承诺。只有发行记录或安装包版本确认包含对应修复后，才能把它当作生产环境已有能力。

如果业务无法接受事件缺口，应把最终结果的权威来源放在服务端运行状态或持久化业务记录中，而非单一 SSE 连接。流适合及时展示进度，持久化状态适合在断线后重新查询与校验。两者配合后，客户端可以在游标恢复失败时先标记状态待核验，再拉取最终状态，而不是悄悄把局部片段拼成完整答案。这是应用架构层的防护，不会替代正确设置可恢复流和游标。

想进一步了解不同平台的模型与 API 能力，可浏览模型平台目录；若在使用第三方服务，可从站点目录核对服务商公开的接入信息，也可以参考站内的 Agent Framework MCP 生命周期文章理解连接关闭边界。无论请求是否经过中转，客户端重连时的游标都应纳入自己的可观测性与测试范围。