很多同学在搭第一个 Multi-Agent 系统时脑子里的模型是这样的多个 Agent 各干各的然后把结果汇总到一起就行了。结果上线后发现某个 Agent 的更新消失了、messages 数组出现重复消息、某个字段被后来的 Agent 悄悄覆盖了排查半天找不到原因。这些问题的根源不是代码写错了是对 LangGraph 的状态合并机制理解不够深。01 Reducer 决定一切没有它并发写就是在碰运气LangGraph 的执行模型是超步superstep在同一个超步里并行运行的节点完成后统一把更新提交给 State由Reducer合并。没有 Reducer 的字段默认行为是覆盖Last Write Wins。三个 Agent 同时写同一个字段只有最后一个活下来——而「最后一个」取决于调度顺序几乎是随机的。Reducer 的签名是(existing: T, update: T) T。你来定义「两份更新怎么合并」LangGraph 负责在超步结束时调用它。importAnnotationStateGraphSendfromlangchain/langgraphimportAIMessagefromlangchain/core/messagesimportasfromuuid// ❌ 没有 Reducer多 Agent 并发写只有最后一个写入会保留constUnsafeStateAnnotationRootresultAnnotationstring// 无 Reducer → 覆盖语义并发写赌博// ✅ 有 Reducer每个 Agent 的写入都会被保留并合并constSafeMultiAgentStateAnnotationRoot// 收集所有 Agent 的结论不互相覆盖agentResultsAnnotationagentstringcontentstringreducer(existing, newItems) default() // 必须设置 default否则第一次调用时 existing undefined 会崩// 消息历史基于 id 去重后追加LangGraph 内置 messagesStateReducer 也是这个逻辑messagesAnnotationanyreducer(existing, newMsgs) constnewSetmap(m: any) idconstfilter(m: any) hasidreturndefault() // Supervisor 用 Send API 并行派发三个 AgentfunctionsupervisorNodestate: typeof SafeMultiAgentState.StatereturnnewSendresearchAgenttask搜集竞品信息newSendcodeAgenttask生成代码骨架newSendwriterAgenttask起草需求文档// 每个 Agent 节点显式设置消息 id避免 messagesStateReducer 去重时碰撞functioncodeAgentNodestate: anyconst代码骨架已生成示意returnagentResultsagentcodeAgentcontentmessagesnewAIMessageidcode-agent-${uuidv4()}content合并过程是串行的——LangGraph 先收集超步内所有节点的更新再依次通过 Reducer 处理。所以 Reducer 本身不用担心线程安全但必须满足结合律无论哪个节点的更新先被合并最终结果应该一样。02 场景一Fan-out 并发写与 messagesStateReducer 的去重陷阱messagesStateReducerLangGraph JS 里的MessagesAnnotation默认行为有一个很多人不知道的去重逻辑新消息的id在已有列表中存在→ 用新消息替换旧消息更新语义新消息的id在已有列表中不存在→ 追加到列表末尾新增语义设计初衷是支持 Human-in-the-Loop 里用户编辑历史消息。但在多 Agent 场景下如果两个 Agent 各自创建AIMessage却没有显式设置id某些运行环境下 id 会碰撞导致 B 的消息静默替换 A 的消息表面上没有报错消息却丢了。// 完整示例子图隔离 消息瘦身 显式 id三件套防御并发写问题constSubgraphStateAnnotationRoottaskAnnotationstringagentNameAnnotationstring// 子图内部消息对父图完全不可见防止中间步骤污染父图internalMessagesAnnotationanyreducer(a, b) concatdefault() constParentStateAnnotationRoottaskAnnotationstring// 父图只收子图的最终结论不收中间步骤subResultsAnnotationagentstringresultstringreducer(existing, newItems) default() // 子图 exit node「瘦身」输出只暴露最终结论给父图functionsubgraphExitNodestate: typeof SubgraphState.StateconstinternalMessagesat1return// 注意这里返回 subResults父图字段而不是 messages// 父图的 messages 完全不受子图内部过程影响subResultsagentagentNameresulttypeofcontentstringcontentJSONstringifycontent子图把 ReAct 的每一步思考都存在internalMessages里父图只拿最终结论。这样父图的 context window 不会随子图运行步数增长而膨胀。03 场景二Race Condition——基于旧快照计算导致增量丢失第三种场景更隐蔽两个 Agent 不是严格并行但都基于「同一个旧 State 快照」做增量计算。时序示例Race ConditionAgent A 读 Statecount 0→ 计算 count 1 → 写入 count 1Agent B 读 Statecount 0→ 计算 count 1 → 写入 count 1最终 count 1而不是预期的 2两人都基于旧值 0 计算A 的写入对 B 来说「不存在」解法是写「增量」而不是「绝对值」把累加逻辑交给 Reducer。// ❌ 直接写绝对值两个 Agent 都基于旧值 0 计算最终结果是 1 而非 2constBadCounterStateAnnotationRootcountAnnotationnumber// 无 Reducer覆盖语义 → race condition// ✅ 写增量每个 Agent 写 [1]Reducer 累积最终聚合时才得出绝对值constGoodCounterStateAnnotationRootcountDeltasAnnotationnumberreducer(existing, newDeltas) default() // Agent A 写 [1]Agent B 写 [1]Reducer 合并后是 [1, 1]// 读取时聚合结果是 2正确functiongetFinalCountstate: typeof GoodCounterState.StatenumberreturncountDeltasreduce(sum, delta) 0// 同理动态 fan-out 时结果数组用 Reducer 收集无论派多少个 worker 都正确functiondispatcherNodestate: typeof ParentState.StateconstparseTaskstask// 可能是 1~N 个returnmap(task, index) newSendworkerAgentagentNameworker-${index}// 只要 subResults 有 Reducer无论派 1 个还是 10 个 worker结果都完整收集04 私有 State vs 共享 State架构层面的根本取舍维度共享 State私有 State子图隔离数据共享方式所有 Agent 直接读写同一份 State子图内部隔离通过入参/出参传递数据冲突风险高需要精心设计 Reducer低冲突面局限在接口层调试难度容易一份 State 一目了然较难需要追踪子图内部状态Context Window 压力高所有 Agent 的消息汇入同一 messages低每个子图有独立 messages适合场景强协作、需要实时共享中间状态强隔离、各 Agent 独立性强选型建议Pipeline 流水线A 的输出是 B 的输入用共享 State简单直接Fan-out 并行多 Agent 各自独立处理最后汇总用子图隔离 结果汇总字段Swarm/网状协作Agent 之间需要互相感知彼此状态用共享 State 精心设计的 Reducer05 四条实践原则与常见坑速查原则一每个会被多个 Agent 写入的字段必须定义 Reducer。原则二Reducer 必须是纯函数且满足结合律。不在 Reducer 里做 API 调用。不写依赖合并顺序的逻辑如字符串拼接带分隔符。原则三子图输出要「瘦身」。exit node 只返回最终结论不把内部 messages 全部暴露给父图。原则四Multi-Agent 场景显式管理消息 id。用uuidv4()自己管不依赖框架自动生成避免messagesStateReducer静默去重。// 速查4 个最常见的坑 解法// 坑 1Reducer 不满足结合律 → 改为数组收集// ❌ reducer: (a, b) a ? ${a}|${b} : b // 顺序不同结果不同// ✅ reducer: (a, b) [...a, ...b] // 数组 concat 满足结合律// 坑 2忘记 default → 第一次调用 existingundefined → 崩溃// ❌ Annotationstring[]({ reducer: (a, b) [...a, ...b] })// ✅ Annotationstring[]({ reducer: (a, b) [...a, ...b], default: () [] })// 坑 3子图 messages 全量流入父图 → context window 膨胀// ❌ 子图 exit node 直接返回 { messages: state.internalMessages }// ✅ 子图 exit node 返回 { subResults: [{ agent, result: lastMsg.content }] }// 坑 4消息没有显式 id → messagesStateReducer 去重时碰撞 → 消息静默丢失// ❌ new AIMessage(结果内容)// ✅ new AIMessage({ id: agent-${uuidv4()}, content: 结果内容 })总结这篇我们把 Multi-Agent 共享状态的并发写入问题拆了个底朝天Reducer 是关键没有 Reducer 的字段在并发写入时行为未定义凡是多 Agent 会写的字段都必须配 Reducer且default不能省三种冲突场景各有解法fan-out 写入用 Reducer 汇总、子图 messages 膨胀用 exit node 瘦身、race condition 用写增量而非绝对值messagesStateReducer 有去重逻辑基于消息 id 决定追加还是替换Multi-Agent 场景必须显式管理消息 id静默去重是最难排查的 bug私有 State vs 共享 State 根据场景选强隔离用子图强协作用共享 State Reducer不要无脑共享Reducer 必须满足结合律合并顺序不可控写成「增量收集 最终聚合」是最稳健的模式学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】