Repository navigation
Description
Is there an existing issue for this?
- I have searched the existing issues
Current Behavior
Title: 流式节点未正常完成时 checkpoint 丢失,导致下一轮对话消息序列结构错乱(LLM 拒绝请求)
问题描述
在使用 ReactAgent.streamMessages(...) 订阅流式输出时,如果外部订阅者在流式过程中取消订阅(如 flux.timeout(...) 超时、前端断开 SSE 连接、断点调试卡住等),会导致:
1.
当前 LLM 节点产生的 AssistantMessage 未被持久化到 checkpoint(MySQL/Postgres/Redis 等 saver);
2.
但该 LLM 节点之前已执行完成的 tool 节点的 ToolResponseMessage 已经持久化了;
3.
用户下次发送消息时,框架从 saver 加载历史消息列表,出现 ... -> assistant(tool_call) -> toolResponse -> user 的结构;
4.
该结构违反了主流 LLM API(OpenAI / DashScope 等)对 messages 序列的硬性约束——tool 角色消息后必须紧跟 assistant 消息,导致 LLM 直接返回 400 错误,拒绝整个请求。
复现步骤
1.
配置一个带 tool calling 的 ReactAgent,使用 MySQL(或任意) CheckpointSaver;
2.
拿到流式 Flux 并加超时:
Flux streamMessages = reactAgent.streamMessages(request.getPrompt(), config);
streamMessages.timeout(Duration.ofSeconds(60)).subscribe(...); // 给前端做 SSE
3.
发送一个会触发 tool call 的问题;
4.
在 com.alibaba.cloud.ai.graph.agent.Agent.extractMessages 处打断点,或在 60 秒内不消费 flux,让其超时;
5.
timeout 触发后,检查数据库 checkpoint 的 messages 列表;
6.
用户再次发送 "请继续"。
预期行为
•
外部订阅超时/取消,只应影响前端 SSE 输出,不应影响框架内部的状态持久化完整性;
•
即便流被中断,已完成的 tool 节点的 ToolResponseMessage 和未完成的 LLM 节点的 AssistantMessage 应当保持配对一致——要么都落库,要么都不落库;
•
下一轮对话加载历史消息时,序列结构应始终合法。
实际行为
数据库中持久化的 messages 列表变为:
user
assistant
user
assistant (with tool_call)
toolResponse ← 缺少紧随其后的 assistant 消息
用户再次输入后变成:
user
assistant
user
assistant (with tool_call)
toolResponse
user ← toolResponse 后直接跟 user,结构非法
发送给 LLM 时被拒绝(400),类似:
"messages: roles must alternate between user/assistant/tool, expected assistant after tool"
根因分析
框架的整个图执行是一条惰性的 Reactor 响应式流,节点的推进、状态合并、checkpoint 持久化全部由下游订阅的 request(n) 拉动驱动,没有独立的后台执行线程。
- 图执行链通过 concatWith + Flux.defer 递归拼接
MainGraphExecutor.java:134-135、NodeExecutor.java:208-209:
return Flux.just(GraphResponse.of(output))
.concatWith(Flux.defer(() -> mainGraphExecutor.execute(context, resultValue)));
下一个节点只有在前一个 Flux onComplete 后才会被 subscribe。 - 流式 LLM 节点的 checkpoint 写入挂在流的末尾 Mono 里
NodeExecutor.processGraphResponseFlux(NodeExecutor.java:543-599):
Mono updateContextMono = Mono.fromRunnable(() -> {
...
context.mergeIntoCurrentState(updateState);
context.buildNodeOutputAndAddCheckpoint(updateState); // :588 才真正写库
...
});
return processedFlux
.concatWith(updateContextMono.thenThen(Flux.defer(() -> mainGraphExecutor.execute(...))));
buildNodeOutputAndAddCheckpoint -> addCheckpoint -> saver.put(...)(GraphRunnerContext.java:244-255)是同步写库,但它被包在 updateContextMono 里,只有当 processedFlux 正常 onComplete 后,这个 Mono 才会被 subscribe。
3. 而 tool 节点是非流式的,checkpoint 是立即同步写的
NodeExecutor.java:204:
NodeOutput output = context.buildNodeOutputAndAddCheckpoint(updateState); // 立即写库
所以 ToolResponseMessage 在 timeout 前已经落库。
4. timeout/cancel 的破坏
flux.timeout(...) 超时后会向上游发 cancel。由于整条链是同一个响应式流(没有 cache()/replay()/独立线程解耦):
•
processedFlux 被 cancel,LLM 的 HTTP 流被中断;
•
concatWith 尾部的 updateContextMono 永远不会被 subscribe,因为 concatWith 依赖前一个 Flux 的 onComplete,而 cancel 不触发 onComplete;
•
于是 :588 的 buildNodeOutputAndAddCheckpoint 从未执行,这条 AssistantMessage 既没进 OverAllState,也没写 checkpoint。
结果:ToolResponseMessage 已落库,配对的 AssistantMessage 丢失,下一轮消息序列非法。
5. 补充:LLM 流式异常时也有类似问题
即便没有外部 timeout,若 LLM 流式过程中抛异常,transformFluxToGraphResponse 的 .onErrorResume(NodeExecutor.java:314-321)会把错误包成 GraphResponse.error 当作数据元素继续发,流会正常 onComplete,updateContextMono 会被执行。但此时 lastData.get() 是 error,resultValue() 不是 Map,updateState 为空 map(:566-575),:582 merge 进去的是空,:588 写的 checkpoint 里仍然没有这条 assistant 消息。同样会导致下一轮消息序列非法。
影响范围
•
任何使用 streamMessages / stream + CheckpointSaver 的场景;
•
外部订阅因任何原因(timeout、前端断开、异常)未正常完成时都会触发;
•
ReactAgent、SequentialAgent 等带 tool calling 的 agent 尤其严重,因为 tool 节点和 model 节点的持久化时机不一致。
建议的修复方向
核心问题是持久化与前端订阅生命周期强耦合。可能的修复方向:
1.
解耦持久化与前端订阅:在内部用 Sinks/publish 多播,持久化由一个独立的内部订阅消费,即使前端断开,内部订阅仍跑完,确保 checkpoint 完整。
2.
流式节点也边吐边写 / 或在 cancel 时兜底写:在 processGraphResponseFlux 的 updateContextMono 之外,增加 doOnCancel 兜底逻辑,在 cancel 时也尝试用已聚合的 lastChatResponseRef 落库。
3.
保证消息序列一致性:在 updateContextMono 里增加校验——若上一条是 toolResponse 且本次没有产出 assistant,要么补一条占位 AssistantMessage,要么回滚到 tool 节点之前的 checkpoint,避免落库一个非法的中间状态。
4.
至少在文档中明确警告:当前 streamMessages 返回的 Flux 不支持外部 timeout/cancel,否则会破坏状态一致性。
环境
•
框架版本:当前 main 分支
•
Saver:MySQL(其他 saver 同理)
•
调用方式:reactAgent.streamMessages(prompt, config) + 外部 flux.timeout(...)
Expected Behavior
No response
Steps To Reproduce
No response
Environment
Spring AI Alibaba version(s):Debug logs
No response
Anything else?
No response
Activity
Jupiter363 commentedon Jul 8, 2026
我重新收敛了一版更保守的修复方案:#4791。
这次没有继续采用 #4790 里的后台继续执行方案。#4790 的思路是:前端 SSE / downstream subscription timeout 或 cancel 后,框架内部仍继续跑完后续节点,把
ToolResponseMessage -> AssistantMessage的链路补完整。这个方案语义更强,但会引入额外并发风险:旧的 cancelled run 可能还在后台写 checkpoint,而用户已经在同一个 thread 上发起了下一轮请求,二者会竞争 latest checkpoint /releaseThread(true)。为了让这个方案安全,需要额外的 lineage guard、release guard,甚至还会牵涉多实例共享 checkpoint 后端时的 saver-level CAS / 分布式锁问题,整体范围会明显扩大。所以我关闭了 #4790,改用 #4791 的 rollback-oriented 方案:保持 Reactor 原有 cancellation 语义,不引入 detached/background execution;如果某次 timeout/cancel 已经留下了不完整的 tool-call checkpoint,下一轮用户输入加载初始状态时会跳过这类不安全 checkpoint,并回退到最近一个可以安全追加 user message 的 checkpoint。
本次修改点:
MessageSequenceValidator,判断 checkpoint 中的messages是否可以作为下一轮 user input 的基底。CompiledGraph.getInitialState(...)不再无条件使用 latest checkpoint,而是从 latest-first checkpoint history 中选择最近的 safe checkpoint。会被跳过的 checkpoint 包括:
tool -> user这种会导致 OpenAI / DashScope-compatible message ordering 非法的历史。已补充覆盖:
ToolResponseMessage结尾时,会回退到上一个 safe checkpoint;本地验证: