Repository navigation
Description
Is there an existing issue for this?
- I have searched the existing issues
Current Behavior
当 FlowAgent 在同一个 threadId 上、配合 CheckpointSaver 被多次调用时,如果本次输入的 UserMessage 文本与 checkpoint 状态中已有消息的文本完全相同,这条新消息会被静默丢弃。合并后的历史最后一条是上一轮的 AssistantMessage,模型因此认为用户没有发起新一轮对话。整个过程没有任何告警或异常日志。
该问题同时影响初始化状态合并(CompiledGraph.getInitialState)和节点回写(GraphRunnerContext.mergeIntoCurrentState),因为 flow 类 Agent 把 messages 注册成了 new AppendStrategy(false),而 AppendStrategy(false) 内部通过 Stream.distinct() 去重——也就是按 equals() 去重。Spring AI 的 AbstractMessage.equals() 比较的是 messageType、textContent 和 metadata,所以两个文本相同的独立 UserMessage 实例会被判定为相等,最终只保留第一个。
常见触发场景:用户回复 继续、yes、重试、1,或者把同一个问题再问一遍。
Expected Behavior
每次调用都应把本次传入的用户消息追加到 messages,即使它的内容与已有消息相同。文本相同的多轮用户输入是完全合法的,不应被去重。
Steps To Reproduce
1. 策略层复现(确定性,无需 LLM):
AppendStrategy strategy = new AppendStrategy(false);
List<Object> oldMessages = List.of(
new UserMessage("hello"),
new AssistantMessage("你好,有什么可以帮你?"));
List<Object> newMessages = List.of(new UserMessage("hello")); // 合法的新一轮输入
Object merged = strategy.apply(oldMessages, newMessages);
// 期望:[UserMessage("hello"), AssistantMessage(...), UserMessage("hello")] (size 3)
// 实际:[UserMessage("hello"), AssistantMessage(...)] (size 2)Stream.distinct() 是稳定去重,会保留先出现的那一条、丢弃后出现的新消息,这恰好与"追加新一轮输入"的语义相反。
Environment
Spring AI Alibaba version(s):
- Spring AI Alibaba:`1.1.2.2`(`master` 分支,commit `<待填>`)
- Spring AI:`1.1.2`
- JDK:`17`
- 涉及模块:`spring-ai-alibaba-agent-framework`、`spring-ai-alibaba-graph-core`
- Checkpoint Saver:`MemorySaver`(复现用),实际上任意 Saver 都受影响Debug logs
No response
Anything else?
1)flow 类 Agent 把 messages 注册为"不允许重复"的追加通道
keyStrategyMap.put("messages", new AppendStrategy(false));位置:spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/FlowGraphBuildingStrategy.java:100
所有使用默认 KeyStrategyFactory 的 flow Agent 都会继承该配置,包括:SequentialAgent、LlmRoutingAgent、ParallelAgent、LoopAgent。
2)AppendStrategy(false) 通过 equals() 去重
return Stream.concat(result.oldValues().stream(), result.newValues().stream())
.distinct()
.collect(Collectors.toList());位置:spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/state/strategy/AppendStrategy.java:87-91
3)Spring AI 的 Message.equals() 是按内容比较的
已用 javap -c 校验 spring-ai-model-1.1.2.jar:AbstractMessage.equals() 依次比较 messageType(引用比较)、Objects.equals(textContent, ...) 和 Objects.equals(metadata, ...),UserMessage 未覆写该方法。
因此第 2 轮的 new UserMessage("hello") 与第 1 轮已保存的 UserMessage("hello") 相等,被 distinct() 移除。
4)合并发生的位置
多轮(checkpoint 恢复)——CompiledGraph.getInitialState(...):
return compileConfig.checkpointSaver()
.flatMap(saver -> saver.get(config))
.map(cp -> OverAllState.updateState(cp.getState(), inputs, keyStrategyMap))
.orElseGet(() -> OverAllState.updateState(new HashMap<>(), inputs, keyStrategyMap));节点回写——GraphRunnerContext.mergeIntoCurrentState(...) → OverAllState.updateState(...),同样应用 AppendStrategy(false)。
为什么当初设计成 allowDuplicate=false
flow 的子 Agent 会把完整的 messages 列表(包含父图传进去的历史)回写到父 state(见 ReactAgent.AgentToSubCompiledGraphNodeAdapter,ReactAgent.java:1011-1030)。如果使用 allowDuplicate=true,每次子 Agent 执行都会把整份历史重复追加一遍。false 的本意应该就是消除这种"回写导致的重复"。
但副作用是:该策略无法区分以下两种情况——
- 回写中包含的、已经存在的历史消息(应该去重);
- 文本恰好与旧消息相同的新一轮用户输入(绝不能去重)。
而基于内容的 equals() 在原理上无法做这个区分。
修复建议
建议优先采用方案 1 或方案 2。
-
只回写增量,并让
messages使用可重复追加的通道。
在子 Agent / flow 节点适配器中,计算子执行期间新增的消息(例如与父快照做 diff,或使用RemoveByHash/ replacement 标记),只追加这部分。这样messages就可以安全地改回new AppendStrategy(),与ReactAgent保持一致(ReactAgent.java:746)。 -
按对象身份/ID 去重,而不是按内容去重。
新增一个MessageAppendStrategy,按对象身份(适用于单次运行内的回写)或按稳定消息 ID(例如创建时写入Message.metadata的 UUID)去重,并让messages使用它;非消息类型的状态仍可保留AppendStrategy(false)。 -
最小化防御性修改。
如果必须保留AppendStrategy(false),可让其对org.springframework.ai.chat.messages.Message类型跳过基于equals()的去重(仅按引用去重),并明确文档说明"对消息类型使用内容去重是不安全的"。 -
最低限度:补充回归测试并文档化该限制,便于用户自行提供
messages对应的KeyStrategyFactory。
建议补充的回归测试
AppendStrategy(false)应保留两个文本相同的独立UserMessage实例——或者 flow Agent 不应把它用于messages。- 多轮 flow Agent 测试:同一
threadId,连续两次传入相同文本,断言 state 中包含两条UserMessage,且最后一条是第二次输入。 - 对
includeContents=true的子 Agent 回写路径增加同样的测试,确保修复不会重新引入历史重复。 - 断言
input与messages的一致性(见下条)。
补充说明
ReactAgent的多轮场景不受影响,因为它使用的是new AppendStrategy()(ReactAgent.java:746);但当includeContents=true时,其回写路径仍可能存在历史重复的问题。input键仍然会拿到本次的新文本(Agent.buildMessageInput),因此在合并之后input与messages会出现不一致——这也是一个值得在测试中断言的症状。
Activity
chengqiangrd commentedon Oct 21, 2026
我在 main(
17e26ff6)上使用 mockChatModel复现了这个问题。分别进行两次独立调用并传入UserMessage("hello")后,最终 state 中只剩一条匹配的用户消息。这个现象在以下三条实际执行路径中都存在:使用MemorySaver的SequentialAgent、禁用缓存并重新构建 Agent 与FileSystemSaver后从文件恢复,以及ParallelAgent。作为对照,嵌套SequentialAgent路径保留了完整历史且没有产生重复。这些测试运行在 JDK 21 上,编译使用--release 17,并非 JDK 17 runtime。这里比较棘手的是共用的合并策略:
AppendStrategy(false)在“checkpoint 恢复后合并本轮新输入”和“接收子图返回的完整历史”两处都会按内容相等性去重;ReactAgent中的removeAll(parentMsgs)也依赖相同的相等性。简单允许重复从静态分析看很可能会再次追加子图中的旧历史;我尚未把这一改动作为修复实际验证,因此不将它视为已确认结论。对象引用身份同样无法跨 checkpoint 序列化保持稳定。想请教维护者:这里更符合项目预期的方向,是为子图结果定义明确的消息增量契约,还是引入可持久化的消息 ID?在改变这些合并语义前,希望能先得到你们的设计指引。
lihanyu1715446406-afk commentedon Nov 4, 2026
Opened #5040 to fix this: flow agents now register
messageswithAppendStrategy(true), so repeated user messages are appended instead of being deduplicated by content. Added a regression test that fails with 2 messages before the change and passes with 3 after it.