多 agent 编排这件事我最早是在一个自动化内容处理的场景里被逼着上手的。当时的需求听起来不复杂把一批原始素材丢进去自动完成信息抽取、事实校验、文案改写、格式排版最后输出成可发布的成品。我一开始用单 agent 硬扛把所有指令塞进一个超长 prompt 里结果就是——它一会儿忘了校验一会儿把排版规则丢了改到第三轮的时候连最初的任务目标都开始漂移。后来我把这条链路拆成四个各司其职的 agent用一个编排层把它们串起来整个流程才真正稳下来。这篇就围绕多 agent 编排的完整实践展开讲清楚它到底是什么、能解决什么问题、适合谁来参考以及我在 LangGraph 这套框架上踩过的坑和总结出的可复现方案。如果你正在做 agent 开发、workflow 编排或者单纯想搞明白多 agent 和单 agent 的边界在哪这篇应该能帮你少走不少弯路。1. 多 agent 编排到底在解决什么问题1.1 单 agent 的能力天花板在哪里很多人刚接触 agent 开发时第一反应是一个足够强的 agent 加上足够长的 prompt 就能干所有事。我一开始也这么想直到实际跑起来才发现单 agent 的问题不是能力不够而是注意力被稀释。当你把信息抽取、逻辑推理、格式约束、风格控制全部塞进一个上下文窗口时模型在每个环节的专注度都会下降。表现最明显的就是长链路任务前几步还靠谱到后面就开始丢约束、编事实、跳步骤。这背后的原因其实不复杂。大模型的推理本质上是基于上下文的概率生成上下文里塞的规则越多、越杂每条规则分到的权重就越低。你可以把它想象成让一个人同时干四份工作写代码、做校对、管排版、还要负责对外沟通。他不是干不了而是每件事都只能做到六十分。单 agent 在简单任务上表现很好但一旦任务需要多个专业视角、多轮校验、或者有严格的流程依赖它的短板就暴露得非常彻底。还有一个更隐蔽的问题错误会累积且难以定位。单 agent 跑一条长链路中间某一步出了偏差你很难判断到底是哪一步的问题因为所有逻辑都耦合在一个上下文里。你想调试只能反复改 prompt 然后整体重跑效率极低。这也是我最终决定拆多 agent 的直接原因——不是为了炫技而是为了可调试、可定位、可替换。1.2 多 agent 编排的核心价值分工、隔离、可组合多 agent 编排的核心思想说白了就是把一个大任务拆成若干职责单一的子任务每个子任务交给一个专门的 agent再用一个编排层控制它们的执行顺序和数据流转。这跟软件工程里的模块化是一个道理每个模块只干一件事模块之间通过明确的接口通信出了问题能快速定位到具体模块。具体来说它带来三个实打实的价值。第一是职责隔离。抽取 agent 只负责抽取校验 agent 只负责校验改写 agent 只负责改写。每个 agent 的 prompt 都很短、很聚焦模型在这个环节的表现会明显更稳定。第二是上下文隔离。每个 agent 只拿到自己需要的那部分信息不会被无关内容干扰。比如校验 agent 不需要知道最终的排版格式它只需要拿到待校验的事实和参考依据。第三是可组合与可替换。某个环节效果不好你可以单独换掉那个 agent甚至换成规则引擎或者外部 API其他环节完全不受影响。这里要澄清一个常见误解多 agent 不等于多个模型。你可以用同一个模型跑所有 agent区别只在于每个 agent 的 prompt、上下文和职责不同。多 agent 是一种架构模式不是模型数量的问题。我见过不少人以为多 agent 就得多花钱调多个模型其实完全不是这么回事。1.3 什么场景该上多 agent什么场景别硬上不是所有任务都值得拆多 agent。拆分的代价是编排复杂度上升你要设计状态结构、定义流转条件、处理异常分支这些都是额外的工程量。如果任务本身很简单比如单轮问答、简单分类、固定格式转换单 agent 甚至一个普通函数调用就够了硬拆多 agent 纯属给自己找麻烦。我的判断标准是这样的当任务满足以下任意两条以上时才考虑多 agent。第一任务有明显的阶段划分且阶段之间有依赖关系第二每个阶段需要不同的专业视角或不同的上下文第三任务需要多轮校验或迭代才能保证质量第四流程中存在条件分支不同情况走不同路径第五你需要对中间结果做独立监控和调试。反过来如果任务是一步到位的、上下文可以完全共享的、不需要迭代的那就老老实实用单 agent。我踩过的最大的坑就是在一个本来很简单的分类任务上硬套多 agent 架构结果编排代码比业务逻辑还长维护成本高得离谱最后又退回单 agent。所以选型这件事克制比激进更重要。2. 用 LangGraph 搭编排骨架的完整思路2.1 为什么选 LangGraph 而不是自己写调度编排层可以自己写无非就是一个 while 循环加一堆 if-else。我最早就是这么干的用 Python 写了个状态机手动管理每个 agent 的输入输出。小规模还行一旦流程变复杂代码就变成了一团乱麻状态散落在各个变量里分支逻辑嵌套得看不清加一个新节点要改好几处。后来换成 LangGraph最大的感受是它把状态和流转这两件事显式化了。LangGraph 的核心抽象是图Graph节点Node代表一个处理单元边Edge代表流转方向整个图共享一个状态对象State。每个节点读取状态、处理、写回状态编排层负责根据条件决定下一步走哪个节点。这种模型的好处是流程一目了然你画出来的图就是代码的结构调试的时候能清楚看到状态在每个节点前后的变化。当然LangGraph 不是唯一选择。市面上还有不少 agent 框架各有侧重。但对我这种想要精细控制流转逻辑、又不想被框架过度封装绑死的人来说LangGraph 的平衡点比较合适它提供了图编排的基础设施但不会替你做太多决定你依然能完全掌控每个节点的行为。下面这张表是我当时选型时对比的几个维度供参考。维度自己写调度LangGraph高度封装框架流转控制精度完全可控但易乱显式图结构清晰黑盒较多难干预状态管理手动易散落统一 State 对象框架托管调试友好度差靠打日志好可逐节点观察一般学习成本低但维护高中等低复杂分支支持手写易出错原生条件边视框架而定2.2 状态设计编排的地基多 agent 编排里状态State设计是最容易被低估、却最影响成败的一环。状态就是所有 agent 共享的那块公共黑板每个 agent 往上写、从上面读。状态设计得好流转逻辑就顺设计得差后面全是补丁。我的经验是状态字段要按生命周期来分。有些字段是全程携带的比如任务 ID、原始输入、全局配置有些字段是阶段产物比如抽取结果、校验结论、改写稿还有些是控制字段比如当前重试次数、错误信息、下一步走向。这三类最好在状态定义里就区分清楚别混在一起。用 LangGraph 的话状态通常用一个 TypedDict 或者 Pydantic 模型来定义。我倾向于用 TypedDict轻量、直观。下面是我在一个内容处理项目里用的状态结构做了简化from typing import TypedDict, List, Optional class PipelineState(TypedDict): # 全程携带 task_id: str raw_input: str config: dict # 阶段产物 extracted_facts: Optional[List[dict]] validation_result: Optional[dict] rewritten_text: Optional[str] final_output: Optional[str] # 控制字段 retry_count: int error: Optional[str] next_step: Optional[str]这里有个关键细节状态字段要允许为空。因为流程刚开始时阶段产物还不存在。用 Optional 标注配合节点里的判空逻辑能避免大量字段不存在的报错。我一开始没注意这点节点里直接访问还没生成的字段跑起来就崩排查了半天才发现是状态初始化的问题。2.3 节点划分的粒度怎么把握节点划分是另一个需要反复权衡的点。划得太粗一个节点干太多事又回到了单 agent 的老问题划得太细节点数量爆炸编排开销和维护成本都上去了。我的经验法则是一个节点对应一个明确的、可独立验证的职责。具体怎么判断你可以问自己这个节点的输出我能不能单独拿出来检查对错如果能它就是一个合理的节点。比如抽取事实这个节点输出是一组结构化事实我可以单独核对每条事实是否准确那它就该独立成节点。而准备上下文这种纯数据搬运的工作就没必要单独成节点塞进相邻节点的前置逻辑里就行。还有一个实践技巧把决策和执行分开。决策节点只负责判断下一步该走哪不干实际业务执行节点只负责干活不做流转判断。这样职责更清晰调试时也更容易定位问题。比如我有个质量评估节点它只输出一个评分和是否通过的标记具体是通过还是打回由条件边来决定。这种分离让整个流程的可读性提升了很多。3. 从零跑通一条多 agent 流水线3.1 环境准备与依赖安装动手之前先把环境弄干净。我强烈建议用虚拟环境别在系统 Python 里直接装不然依赖冲突能让你怀疑人生。Python 版本建议 3.10 以上LangGraph 和一些相关库对版本有要求。下面是完整的准备步骤按顺序来就行。# 创建虚拟环境 python -m venv venv # 激活Linux/Mac source venv/bin/activate # 激活Windows venv\Scripts\activate # 安装核心依赖 pip install langgraph langchain-core langchain-openai如果你用的是其他模型服务把 langchain-openai 换成对应的集成包即可。装完之后建议跑一句pip list确认版本尤其是 langgraph 的版本不同版本 API 有差异网上很多教程对不上就是因为版本不同。我踩过一次坑照着旧教程写的代码结果StateGraph的导入路径变了报错报得莫名其妙后来一查版本才发现问题。提示装依赖时把版本号固定下来写进 requirements.txt。多 agent 项目依赖较多不锁版本的话过段时间换个环境重装很可能就跑不起来了。3.2 定义状态与初始化图环境好了之后第一步是定义状态和初始化图。状态用上一节说的思路设计图用 LangGraph 的 StateGraph 来建。下面是一个最小可运行的骨架from langgraph.graph import StateGraph, END from typing import TypedDict, Optional class State(TypedDict): raw_input: str extracted: Optional[str] validated: Optional[str] output: Optional[str] retry_count: int # 初始化图绑定状态类型 workflow StateGraph(State)这里StateGraph(State)把状态类型绑定了进去后面每个节点函数的入参和返回值都要符合这个结构。初始化完图之后节点还没加边也没连这时候的图是空的。接下来就是往里面加节点、连边。有个细节要注意节点函数的返回值是状态更新不是完整状态。也就是说节点只需要返回它修改的那部分字段LangGraph 会自动合并到全局状态里。这个设计很省事但也容易踩坑——如果你返回了一个字段但类型不对合并时会报错。我建议每个节点函数都明确标注返回类型让类型检查帮你提前发现问题。3.3 编写第一个 agent 节点节点本质上就是一个函数接收状态干活返回状态更新。下面是一个抽取节点的例子它调用模型从原始输入里抽取结构化信息from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0) def extract_node(state: State) - dict: prompt f从下面的内容中抽取关键事实每条一行\n{state[raw_input]} resp llm.invoke(prompt) return {extracted: resp.content}这个节点很纯粹读 raw_input调模型写 extracted。它不关心下一步是谁也不关心校验怎么做。这就是职责单一的好处——这个函数你可以单独测试喂一段输入看输出对不对完全不用启动整个图。写节点时有几个经验点。第一temperature 尽量调低抽取、校验这类任务需要稳定输出temperature 高了结果会飘。第二prompt 里明确输出格式比如要求每条一行或者输出 JSON这样下游节点解析起来才省事。第三节点里做好异常捕获模型调用可能超时或返回异常别让一个节点的失败把整个流程带崩。我一般会在节点里 try-except把错误写进 state 的 error 字段让编排层决定怎么处理。3.4 用条件边控制流转节点加完之后重头戏是连边。普通边用add_edge直接连条件边用add_conditional_edges根据状态里的某个字段决定走哪条路。这是多 agent 编排最核心的能力——让流程根据实际情况动态分支。def route_after_validate(state: State) - str: if state.get(validated) pass: return rewrite if state[retry_count] 2: return give_up return extract # 打回重抽 workflow.add_conditional_edges( validate, route_after_validate, { rewrite: rewrite, give_up: END, extract: extract, } )这段逻辑的意思是校验通过就去改写重试超过两次就放弃否则打回重新抽取。条件边让整个流程有了自我纠错的能力这是单 agent 很难优雅实现的。注意route_after_validate返回的是字符串这个字符串要在后面的映射字典里有对应否则会报错。我第一次写的时候漏了一个分支跑起来直接抛异常查了半天才发现是映射不全。3.5 编译、运行与观察执行过程节点和边都连好之后调用compile()把图编译成可执行对象然后invoke()传入初始状态就能跑起来app workflow.compile() initial_state { raw_input: 待处理的原始内容, extracted: None, validated: None, output: None, retry_count: 0, } result app.invoke(initial_state) print(result[output])跑起来之后观察执行过程比看最终结果更重要。LangGraph 支持流式输出每个节点的状态变化我强烈建议在开发阶段打开这个功能能看到状态在每个节点前后的差异。这样一旦结果不对你能立刻定位是哪个节点出的问题而不是对着最终输出瞎猜。for event in app.stream(initial_state): for node_name, node_output in event.items(): print(f节点 {node_name} 输出: {node_output})这个 stream 输出是我调试多 agent 流程时用得最多的工具。它把黑盒变成了白盒每个节点的输入输出都清清楚楚。实测下来有了它定位问题的速度能快好几倍。4. 让流程真正稳下来的几个关键设计4.1 重试与降级别让一个节点拖垮全局多 agent 流程里任何一个节点都可能失败模型超时、返回格式不对、外部 API 挂了。如果不做处理一个节点的失败就会让整条链路崩掉。我的做法是给每个关键节点配一套重试 降级策略。重试的逻辑很简单节点失败时把 retry_count 加一然后通过条件边打回重跑。但要设一个上限超过上限就降级。降级的意思是用次优方案兜底保证流程能走完。比如抽取节点连续失败可以降级成用规则做简单抽取虽然质量差一点但至少流程不中断。这里有个容易忽略的点重试要有区分度。如果每次重试都用完全一样的输入和 prompt那大概率还是失败。我的经验是重试时稍微调整一下比如换个措辞、降低要求、或者换一个备用模型。这样重试才有意义而不是无脑循环。4.2 上下文传递只给该给的别一股脑塞多 agent 相比单 agent 的一大优势就是上下文隔离但这个优势需要你主动去用。如果你在每个节点里都把整个 state 塞进 prompt那跟单 agent 没区别还多了编排开销。正确的做法是每个节点只提取自己需要的那部分状态。校验节点只需要待校验内容和参考依据不需要原始输入的全部细节改写节点只需要校验通过的事实和风格要求不需要抽取过程的中间日志。这样每个节点的 prompt 都短而聚焦模型表现更稳token 消耗也更低。我做过一个对比同样的任务全量上下文传递和按需传递前者 token 消耗是后者的三倍多而且输出质量还更差。原因就是无关信息干扰了模型的判断。所以上下文传递这件事克制是美德。4.3 状态字段的读写冲突怎么避免多个节点读写同一个状态很容易出现冲突。最常见的问题是两个节点都以为自己拿到的是最新状态结果其中一个用的是旧值。这在并行节点里尤其明显。避免冲突的核心原则是一个字段尽量只由一个节点写。如果确实需要多个节点写同一个字段那就要明确写入顺序或者用追加而不是覆盖的方式。比如日志类字段用列表追加而不是每次覆盖。LangGraph 对某些字段支持 reducer归约函数可以指定多个节点写入时如何合并这个在需要聚合结果的场景里很有用。还有一个实践建议状态字段命名要能体现它的来源和用途。比如extracted_facts比data清晰得多validation_result比result明确。命名清晰了节点之间的数据依赖关系一目了然冲突也更容易提前发现。4.4 可观测性日志、追踪与回放多 agent 流程一旦上线可观测性就是生命线。你不可能每次都手动跑一遍看结果必须有一套机制能告诉你流程走到哪了、每个节点花了多久、哪一步失败了、失败时的状态是什么。我的做法是三层。第一层是结构化日志每个节点进出都打一条日志带上 task_id、节点名、耗时、状态摘要。第二层是状态快照每个节点执行后把状态存一份出问题时可以回放。第三层是关键指标监控比如各节点的失败率、平均耗时、重试次数分布。这三层搭起来之后流程基本就是透明的出问题能快速定位。回放这个能力特别值得投入。有了状态快照你可以把任意一次失败的执行重放一遍逐节点检查。我靠这个能力定位过好几个偶发的、难以复现的问题如果没有回放那些问题可能永远查不出来。5. 多 agent 编排里那些没人告诉你的坑5.1 循环依赖与死循环条件边带来了灵活性也带来了死循环的风险。如果 A 节点打回 BB 又打回 A而重试条件没设好流程就会无限循环。我踩过一次一个校验节点和抽取节点互相打回跑了十几分钟才发现不对劲token 烧了一大把。防范死循环的核心是给每个循环设硬上限。不管是重试次数还是循环轮数都要有一个明确的、不可突破的上限。而且这个上限要放在状态里由编排层统一判断不能依赖单个节点的自觉。另外条件边的路由函数里兜底分支一定要有确保任何情况下都有明确的下一步不会卡住。5.2 状态膨胀与性能下降流程跑得越久状态里积累的数据越多如果不清理会越来越臃肿。表现就是每个节点的 prompt 越来越长token 消耗越来越大速度越来越慢。这个问题在长流程里特别明显。解决办法是给状态做垃圾回收。阶段产物用完就清掉或者只保留摘要。比如抽取的中间结果在校验通过后就可以从状态里移除只留最终结论。日志类字段也要定期截断别无限追加。我一般会在每个节点返回时顺手清理掉不再需要的字段保持状态精简。5.3 节点间的理解偏差这是最隐蔽的坑上游节点输出的格式下游节点理解错了。比如上游输出的是 JSON 字符串下游以为是 Python 字典直接按字典访问结果报错。或者上游输出的字段名和下游期望的不一致导致数据丢失。避免这个问题的关键是把节点间的接口约定显式化。我现在的做法是每个节点的输入输出都用明确的类型标注关键字段用 Pydantic 模型做校验。上游输出后下游先校验格式再使用格式不对就走异常分支。这样虽然多写了一点代码但省下了大量排查数据为什么丢了的时间。5.4 成本失控的隐形陷阱多 agent 流程的 token 消耗比单 agent 高这是必然的因为多了编排开销和节点间的数据传递。但如果不加控制成本会失控得很快。我见过一个流程因为状态膨胀加上无脑重试单次执行的成本是预期的十几倍。控制成本有几个抓手。第一精简每个节点的上下文只给必要的。第二限制重试次数别让失败节点无限重跑。第三用小模型跑简单节点比如格式转换、简单分类这种没必要上大模型。第四监控单次执行的成本设一个阈值超了就告警。这几条做下来成本能压到合理范围。6. 从能跑到好用进阶优化方向6.1 并行化能同时干的别串着干有些节点之间没有依赖关系完全可以并行执行没必要串着跑。比如多个独立的校验维度可以同时跑最后汇总结果。LangGraph 支持并行分支把没有依赖的节点并行化能显著缩短整体耗时。但并行化有个前提并行节点之间不能有状态写冲突。如果两个并行节点都写同一个字段结果就不确定了。所以并行化之前先理清状态依赖确保并行节点写的是不同的字段或者用 reducer 明确合并规则。6.2 人机协同关键节点留个人工确认不是所有流程都适合全自动。有些关键决策比如最终发布、大额操作留一个人工确认环节会更稳妥。LangGraph 支持在流程中插入中断点执行到那里暂停等人工确认后再继续。这个能力在内容审核、财务处理这类场景里特别有用。我的做法是把风险高、不可逆的节点设成需要人工确认其他节点全自动。这样既保证了效率又守住了关键风险点。6.3 动态编排根据任务类型走不同的图固定的图适合固定流程但现实中任务往往是多样的。这时候可以考虑动态编排根据任务类型选择不同的子图或者不同的节点组合。LangGraph 支持子图嵌套可以把常用的流程封装成子图主图根据情况调用不同的子图。这个方向我还在探索目前的做法是把流程分成几个档位简单任务走轻量图复杂任务走完整图。这样既保证了简单任务的效率又保留了复杂任务的处理能力。6.4 评估与迭代怎么知道编排变好了多 agent 流程的优化不能靠感觉得有评估。我的做法是建一个测试集包含各种典型任务和边界情况每次改动后跑一遍对比关键指标成功率、平均耗时、平均成本、各节点失败率。有了这套评估优化才有方向不然就是瞎调。评估集要持续维护把线上遇到的失败案例补充进去。这样评估集会越来越贴近真实场景优化也越有针对性。我现在的评估集里有一半以上都是从线上真实失败案例里攒出来的这些案例比拍脑袋想的测试用例有价值得多。7. 一些实操中的零散心得关于模型选择我的建议是别迷信大模型。很多节点用中等模型甚至小模型就能跑得很好尤其是格式转换、简单抽取这类任务。把大模型留给真正需要推理的节点成本和质量都能兼顾。关于 prompt 编写每个 agent 的 prompt 都要独立打磨别指望一套 prompt 走天下。抽取的 prompt 强调准确和完整校验的 prompt 强调严格和挑刺改写的 prompt 强调风格和流畅。每个 agent 的目标不同prompt 的侧重点就该不同。关于调试先单节点测再连起来测。每个节点单独喂输入确认输出符合预期再往图里连。这样出问题时你能确定是节点本身的问题还是编排的问题。我见过太多人一上来就跑整图结果报错都不知道从哪查。关于版本管理状态结构和图结构都要版本化。流程改了之后老的状态快照可能和新结构不兼容回放会出问题。我的做法是给状态结构加一个版本号回放时先检查版本不匹配就跳过或者做转换。关于文档把图的结构画出来贴在项目里。多 agent 流程的复杂度光看代码很难快速理解。一张清晰的流程图能让新加入的人几分钟就搞明白整个流程。这个投入产出比极高强烈建议做。最后说一个心态上的体会。多 agent 编排很容易陷入过度设计的陷阱总想把流程拆得更细、加更多节点、支持更多分支。但每多一个节点就多一份维护成本和出错概率。我现在的原则是能用简单方案解决的绝不引入复杂度。多 agent 是手段不是目的让任务稳定高效地完成才是目的。踩过几次过度设计的坑之后我越来越倾向于够用就好。这套东西我陆陆续续打磨了大半年从最开始的手写状态机到后来的 LangGraph中间推翻重来了好几次。现在回头看最大的收获不是学会了某个框架而是想清楚了什么该拆、什么该合、什么该交给模型、什么该用规则兜底这些判断。这些判断没有标准答案只能靠一个个项目喂出来。希望这篇里的经验和坑能让你在搭自己的多 agent 流程时少绕几个弯。