1. 多 Agent 编排到底在解决什么问题1.1 从单 Agent 到多 Agent 的必然演进先说结论单 Agent 能做的事天花板比大多数人想象的要低得多。我去年帮一个团队做智能客服系统一开始就是单个 Agent 包打天下——理解用户意图、查知识库、调工单接口、生成回复全塞在一个提示词里。前两周跑得挺好到第三周就开始出问题工具调用越来越不稳定上下文越来越长模型开始“忘记”自己该干什么。最典型的一个 bug 是用户问“帮我查一下上个月的订单”Agent 居然去调了退款接口。这不是模型不行而是单 Agent 的认知负荷过载了。一个 Agent 同时承担意图识别、任务规划、工具选择、结果校验、回复生成五个角色就像让一个人同时当产品经理、程序员、测试和运维短期能扛长期必崩。多 Agent 编排的核心思路就是分而治之把一个大任务拆成若干子任务每个子任务交给专门的 Agent 处理Agent 之间通过明确的协议传递信息和状态。这跟微服务架构的思路是一脉相承的——单体应用拆成微服务每个服务只干一件事通过 API 通信。1.2 编排和“堆 Agent”是两回事很多人一听多 Agent第一反应是“那我多开几个 Agent 不就行了”。我见过一个项目开发者开了 8 个 Agent结果比单 Agent 还慢还乱。问题出在没有编排。编排Orchestration这个词来自工作流领域核心含义是定义谁在什么时候做什么、做完之后交给谁。没有编排的多 Agent 就是一群无头苍蝇各自为战互相等待甚至死锁。一个合格的多 Agent 编排系统至少要解决四个问题任务分解大任务怎么拆成子任务拆到什么粒度角色分配每个子任务交给哪个 AgentAgent 的能力边界在哪状态传递Agent 之间怎么传数据传什么格式传多少流程控制串行还是并行失败了怎么重试超时了怎么降级这四个问题不解决Agent 越多越乱。下面这张表是我总结的单 Agent 和多 Agent 的适用边界你可以对照自己的场景判断维度单 Agent 适用多 Agent 适用任务复杂度单一意图3 步以内多意图5 步以上工具数量少于 5 个10 个以上上下文长度单轮对话为主多轮、跨会话错误容忍度低错了重来高可局部重试开发成本低一个提示词搞定高需要编排框架调试难度低日志集中高需要链路追踪1.3 为什么现在谈多 Agent 编排正当时两年前谈多 Agent 编排大家会觉得是屠龙之术——模型能力不够工具生态不成熟编排框架几乎没有。现在情况完全变了。模型侧主流大模型在函数调用、结构化输出、长上下文上的能力已经足够支撑复杂编排。工具侧各种 Agent 框架和编排库层出不穷LangGraph 就是其中比较有代表性的一个。工程侧可观测性工具、链路追踪、状态管理这些配套也慢慢跟上了。更重要的是业务场景开始真正需要多 Agent。比如自动化代码审查需要理解代码、检查规范、生成建议、验证建议四个环节每个环节的提示词和工具集都不一样硬塞进一个 Agent 效果很差。再比如深度研究助手需要搜索、阅读、总结、交叉验证、生成报告这本身就是一条流水线。所以现在学多 Agent 编排不是赶时髦而是场景倒逼。你迟早会遇到单 Agent 搞不定的任务到时候再学就晚了。2. 编排框架选型LangGraph 凭什么值得学2.1 主流编排方案的横向对比在动手之前先搞清楚市面上有哪些编排方案各自适合什么场景。我把常见的几类列出来方案类型代表核心思路适合场景坑点链式编排LangChain LCEL线性管道A 的输出给 B简单流水线分支和循环支持弱图编排LangGraph状态图节点边复杂流程、循环、条件分支学习曲线陡角色编排AutoGen多 Agent 对话协作讨论、辩论容易发散成本高事件编排自研事件总线发布订阅大规模异步调试困难硬编码纯 Pythonif-else 调度流程固定的小项目扩展性差我个人的建议是流程简单用 LCEL流程复杂用 LangGraph需要多 Agent 讨论用 AutoGen规模再大就自研。对于大多数想入门多 Agent 编排的开发者LangGraph 是最佳起点因为它把“图”这个抽象做得足够通用既能表达简单流水线也能表达复杂的状态机。2.2 LangGraph 的核心抽象状态、节点、边LangGraph 的心智模型非常简单就三个概念State状态一个共享的数据结构所有节点都能读写。通常是个字典或 TypedDict。Node节点一个函数接收 State返回 State 的更新。每个节点就是一个 Agent 或一个处理步骤。Edge边定义节点之间的流转关系。可以是固定的A 之后必走 B也可以是条件的根据 State 决定走 B 还是 C。这三样东西组合起来就能表达任意复杂的流程。我画个简单的类比State 是共享内存Node 是函数Edge 是调用关系。如果你写过状态机或者工作流引擎这个概念一秒钟就懂了。LangGraph 相比 LCEL 最大的优势是支持循环。LCEL 是 DAG有向无环图不能回头。但很多 Agent 场景需要循环比如“生成代码 → 测试 → 失败 → 重新生成”这就是一个环。LangGraph 天然支持这种结构。2.3 环境准备Python 安装与依赖管理动手之前先把环境搞干净。我见过太多人因为环境问题卡在第一步这里给一套我常用的流程。Python 版本建议 3.10 以上因为 LangGraph 用了一些新语法特性。安装 Python 本身不复杂官网下载安装包一路下一步就行Windows 记得勾选“Add Python to PATH”。装完之后验证python --version pip --version依赖管理我强烈建议用虚拟环境不要往全局环境里装。用 venv 就行python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate激活之后装依赖pip install langgraph langchain-openai langchain-core如果你需要用到 numpy 做数据处理或者 cv2 做图像处理也一并装上pip install numpy opencv-python注意opencv-python 在某些 Linux 环境下需要额外的系统依赖装不上先看报错信息通常是缺 libGL。Ubuntu 下apt install libgl1就能解决。2.4 一个最小可运行示例光说不练假把式。下面是一个最小的 LangGraph 示例两个节点串行执行from typing import TypedDict from langgraph.graph import StateGraph, END class State(TypedDict): input: str step1_result: str step2_result: str def node_a(state: State) - State: return {step1_result: f处理了: {state[input]}} def node_b(state: State) - State: return {step2_result: f二次处理: {state[step1_result]}} graph StateGraph(State) graph.add_node(a, node_a) graph.add_node(b, node_b) graph.set_entry_point(a) graph.add_edge(a, b) graph.add_edge(b, END) app graph.compile() result app.invoke({input: hello}) print(result)跑通这个示例你就理解了 LangGraph 的基本套路定义 State、写节点函数、连边、编译、调用。后面所有的复杂编排都是在这个骨架上加东西。3. 多 Agent 编排的核心设计模式3.1 主管模式一个大脑指挥多个手脚这是最常用也最容易理解的模式。一个 Supervisor Agent 负责理解任务、分解任务、分派给 Worker AgentWorker 干完活把结果交回来Supervisor 决定下一步。这个模式的好处是控制流清晰所有决策集中在一个地方调试的时候只需要看 Supervisor 的日志。坏处是 Supervisor 容易成为瓶颈任务一多就忙不过来。适用场景任务分解逻辑明确、Worker 职责单一的场合。比如一个内容生产流水线Supervisor 负责拆解“写一篇技术文章”这个任务分给“资料搜集 Agent”“大纲 Agent”“正文 Agent”“校对 Agent”。实现上Supervisor 通常是一个带函数调用能力的 LLM 节点它根据当前 State 决定下一个该谁干。LangGraph 里用条件边来实现def supervisor(state: State) - str: # 根据 state 判断下一步 if not state.get(research_done): return researcher elif not state.get(draft_done): return writer else: return reviewer graph.add_conditional_edges(supervisor, supervisor, { researcher: researcher, writer: writer, reviewer: reviewer, })3.2 流水线模式各司其职顺序推进流水线模式把任务拆成固定顺序的几个阶段每个阶段一个 Agent前一个的输出是后一个的输入。这是最接近传统工作流的模式也最容易理解和实现。好处是可预测性强每个阶段的输入输出格式固定测试起来方便。坏处是灵活性差中间某个阶段出问题整个流程就卡住了。适用场景流程固定、阶段边界清晰的任务。比如文档处理流水线解析 → 分块 → 嵌入 → 检索 → 生成。再比如代码审查流水线拉取代码 → 静态检查 → 逻辑审查 → 生成报告。流水线模式在 LangGraph 里就是简单的 add_edge 串联不需要条件边。但要注意错误处理每个节点都要考虑失败的情况不能让异常直接冒泡把整个图搞崩。3.3 辩论模式多个 Agent 互相挑战这个模式比较有意思。多个 Agent 针对同一个问题给出各自的答案然后互相评论、挑战、修正最后收敛到一个共识。适合需要多角度思考的场景比如方案评审、风险评估。实现上通常是两个或三个 Agent 轮流发言用一个“裁判”Agent 判断是否达成共识。LangGraph 里用循环边实现def should_continue(state: State) - str: if state[round] 3 or state[consensus]: return end return debate graph.add_conditional_edges(judge, should_continue, { debate: debater_a, end: END, })这个模式最大的坑是成本。每轮辩论都要调用多次 LLM轮数一多 token 消耗惊人。我的经验是设置硬性轮数上限同时给裁判 Agent 一个明确的“达成共识”判断标准避免无限循环。3.4 层级模式大团队套小团队当任务规模大到一定程度扁平的结构就不够用了。层级模式把 Agent 组织成树状顶层 Supervisor 管几个中层 Supervisor每个中层 Supervisor 管一组 Worker。这个模式适合超大规模任务比如“分析一家公司的财报”可以拆成“财务数据提取”“行业对比”“风险分析”三个子团队每个子团队内部再细分。代价是复杂度爆炸。层级越深状态传递越麻烦调试越困难。我的建议是层级不要超过三层超过三层说明你的任务拆分有问题应该考虑拆成多个独立的图。4. 状态管理与 Agent 间通信的实操细节4.1 State 设计共享什么隔离什么State 设计是多 Agent 编排里最容易翻车的地方。设计得好Agent 之间配合流畅设计得差要么信息不够用要么状态污染。我的经验法则是共享必要信息隔离中间过程。具体来说所有 Agent 都需要的全局信息放 State比如用户原始输入、任务目标、全局配置单个 Agent 的中间产物不要直接塞进 State而是存到外部文件、数据库State 里只放引用State 的字段要少而精超过 10 个字段就要考虑拆分了LangGraph 的 State 支持 reducer可以定义字段的合并策略。比如多个 Agent 同时往一个列表里追加内容from typing import Annotated from operator import add class State(TypedDict): messages: Annotated[list, add] current_task: str这里的Annotated[list, add]表示这个字段的更新方式是追加而不是覆盖。这个细节很关键不设置的话后一个 Agent 会把前一个的结果覆盖掉。4.2 消息传递结构化还是自然语言Agent 之间传消息有两种风格结构化JSON、字典和自然语言纯文本。两种我都用过各有优劣。结构化消息的好处是解析稳定下游 Agent 不用猜格式。坏处是表达能力受限复杂信息塞不进固定 schema。自然语言消息的好处是灵活坏处是下游解析容易出错。我的实践是混合使用控制信息用结构化内容信息用自然语言。比如{ task_id: t001, status: success, content: 这是 Agent A 生成的正文内容可能很长..., metadata: {tokens: 1234, duration: 2.3} }这样下游 Agent 既能稳定拿到状态又能灵活处理内容。4.3 记忆管理短期、长期、共享Agent 的记忆分三层短期记忆当前任务内的上下文存在 State 里任务结束就丢长期记忆跨任务的知识存在向量数据库或文件里共享记忆多个 Agent 都能访问的公共区域比如一个共享的草稿文档短期记忆最简单State 里放就行。长期记忆需要接向量库LangGraph 支持 checkpointer 机制可以把 State 持久化到 SQLite 或 Postgres。共享记忆比较麻烦需要处理并发读写我的做法是用一个专门的“记忆 Agent”来管理其他 Agent 通过它读写。注意长期记忆不是越多越好。我见过一个项目把所有历史对话都塞进向量库结果检索出来的全是噪音。记忆要有选择地存只存那些对未来任务有价值的结论性信息。4.4 并发控制什么时候该并行多 Agent 不一定非要串行。有些任务可以并行比如“同时搜索三个不同的数据源”并行能大幅缩短总耗时。LangGraph 支持并行节点只要多个节点从同一个节点出发且没有相互依赖就会自动并行执行。但并行有几个坑状态冲突多个节点同时写同一个 State 字段结果不确定。解决方法是给字段加 reducer或者让并行节点写不同的字段。资源竞争并行调用 LLM 会瞬间打满 API 配额需要加限流。错误传播一个并行分支失败其他分支怎么办要么全部回滚要么部分成功。这个要在设计阶段就想清楚。我的建议是默认串行确认无依赖再并行。并行带来的复杂度提升往往超过它节省的时间。5. 常见问题排查与避坑实录5.1 Agent 陷入死循环怎么办这是多 Agent 编排最常见的问题。两个 Agent 互相等待或者一个 Agent 反复调用同一个工具流程永远走不到 END。排查思路分三步看日志确认是哪个节点在重复执行重复的触发条件是什么查条件边条件函数的判断逻辑是不是有漏洞比如某个状态永远为 False加护栏给循环加最大轮数限制超过就强制跳出LangGraph 里可以给 State 加一个计数器class State(TypedDict): loop_count: int def should_continue(state: State) - str: if state[loop_count] 10: return end return continue提示护栏不是万能的它只是防止流程卡死真正的问题还是要从条件逻辑上解决。我踩过的坑是条件函数里用了!而不是导致判断永远为真。5.2 状态污染导致下游 Agent 行为异常状态污染的表现是某个 Agent 突然开始做不属于它职责的事或者输出格式完全不对。原因通常是上游 Agent 往 State 里写了不该写的东西。比如上游 Agent 把“思考过程”也写进了 State下游 Agent 看到一堆无关内容就被带偏了。解决方法是严格定义每个字段的写入者在代码层面做约束。我的做法是给 State 字段加注释标明谁写谁读class State(TypedDict): # 写入: supervisor, 读取: all task_goal: str # 写入: researcher, 读取: writer research_result: str # 写入: writer, 读取: reviewer draft: str这样团队协作的时候谁该写哪个字段一目了然。5.3 Token 消耗失控的排查与优化多 Agent 系统的 token 消耗通常是单 Agent 的 3 到 10 倍因为每个 Agent 都要带上下文还要互相传消息。失控的典型表现是账单突然暴涨。优化手段有几个精简 State只传必要信息大文本存外部压缩历史老消息做摘要不要原样传递缓存结果相同输入直接返回缓存不重复调用选对模型简单任务用小模型复杂任务才用大模型我做过一个对比测试同样的任务优化前消耗 12 万 token优化后降到 3 万效果基本没差别。关键就是别把整个对话历史无脑传给每个 Agent。5.4 常见问题速查表现象可能原因排查方向解决手段流程卡住不动条件边判断错误打印 State 看条件值修正条件逻辑加护栏Agent 输出格式错乱状态污染检查上游写入约束字段写入者Token 消耗暴涨上下文过长统计每次调用 token精简 State压缩历史并行节点结果不一致状态竞争检查并发写入加 reducer 或分离字段工具调用失败率高参数格式不对看工具调用日志加参数校验用结构化输出整体响应慢串行节点太多分析各节点耗时无依赖节点改并行5.5 调试技巧链路追踪怎么做多 Agent 系统的调试比单 Agent 难得多因为一次请求会经过多个节点每个节点都可能出问题。没有链路追踪你根本不知道是哪一步出的错。我的做法是给每个节点加统一的日志装饰器记录输入、输出、耗时、token 消耗import time import functools def trace_node(func): functools.wraps(func) def wrapper(state): start time.time() print(f[{func.__name__}] 输入: {state}) result func(state) print(f[{func.__name__}] 输出: {result}, 耗时: {time.time()-start:.2f}s) return result return wrapper生产环境建议接 LangSmith 或者自建追踪系统把每次调用的链路可视化。这个投入是值得的能省下大量排查时间。6. 从 Demo 到生产多 Agent 系统的工程化6.1 安全边界Agent 能做什么不能做什么Agent 一旦接入真实工具就有了实际操作能力。这时候安全边界必须划清楚。我见过一个 Agent 因为提示词注入把数据库里的数据全删了教训惨痛。几条硬性规则工具白名单只给 Agent 开放必要的工具不要图省事全开参数校验所有工具调用的参数都要校验不能直接透传权限隔离不同 Agent 用不同的凭证最小权限原则操作审计所有工具调用都记日志可追溯注意提示词注入是多 Agent 系统的高危风险。用户输入的内容如果直接进了 Agent 的提示词就可能被利用。防御方法是把用户输入和系统提示词严格隔离用结构化格式传递。6.2 性能优化让多 Agent 跑得更快多 Agent 系统的性能瓶颈通常在两个地方LLM 调用和状态传递。LLM 调用优化能并行的并行能缓存的缓存能用小模型的不用大模型。我做过统计一个典型的多 Agent 流程里60% 的 LLM 调用是可以用小模型替代的成本能降一半以上。状态传递优化State 不要太大大对象存外部。LangGraph 的 checkpointer 会序列化整个 StateState 越大序列化越慢。我见过一个项目 State 里塞了几十 MB 的文本每次节点切换都要序列化一遍慢得离谱。6.3 可观测性生产环境必须有的监控Demo 跑通和生产可用之间差的就是可观测性。生产环境至少要监控这几个指标成功率每次请求是否成功完成耗时分布P50、P95、P99 各是多少Token 消耗按任务、按 Agent 统计工具调用成功率哪个工具最容易失败异常分布哪类错误最多这些指标接上告警出问题第一时间知道。我吃过亏一个 Agent 静默失败了一周才发现用户投诉了一堆。6.4 版本管理与灰度发布Agent 系统的提示词、工具、编排逻辑都会变每次变更都可能影响效果。所以版本管理很重要。我的做法是提示词单独存文件用 git 管理编排逻辑用配置文件描述不改代码就能调整新版本先灰度 10% 流量观察指标再全量这样出问题能快速回滚不至于全量翻车。7. 一个完整的实战案例技术文章生成流水线7.1 需求拆解与 Agent 划分说了这么多理论来个完整的实战案例。需求是输入一个技术主题自动生成一篇 3000 字的技术文章。拆解一下这个任务可以分成四个阶段资料搜集搜索相关资料提取关键信息大纲生成根据资料生成文章大纲正文撰写按大纲逐节写正文校对润色检查逻辑、修正错误、润色语言对应四个 AgentResearcher、Outliner、Writer、Reviewer。用流水线模式串联Reviewer 发现问题可以打回 Writer 重写形成一个带循环的流水线。7.2 核心代码骨架from typing import TypedDict, Annotated from operator import add from langgraph.graph import StateGraph, END class ArticleState(TypedDict): topic: str research: str outline: str draft: str review_feedback: str revision_count: int def researcher(state: ArticleState) - ArticleState: # 调用搜索工具整理资料 return {research: ...} def outliner(state: ArticleState) - ArticleState: # 根据资料生成大纲 return {outline: ...} def writer(state: ArticleState) - ArticleState: # 根据大纲写正文如果有反馈则修订 return {draft: ..., revision_count: state.get(revision_count, 0) 1} def reviewer(state: ArticleState) - ArticleState: # 审查正文给出反馈 return {review_feedback: ...} def should_revise(state: ArticleState) - str: if state[revision_count] 3: return end if 通过 in state[review_feedback]: return end return revise graph StateGraph(ArticleState) graph.add_node(researcher, researcher) graph.add_node(outliner, outliner) graph.add_node(writer, writer) graph.add_node(reviewer, reviewer) graph.set_entry_point(researcher) graph.add_edge(researcher, outliner) graph.add_edge(outliner, writer) graph.add_edge(writer, reviewer) graph.add_conditional_edges(reviewer, should_revise, { revise: writer, end: END, }) app graph.compile()这个骨架跑通之后每个节点的具体实现可以逐步替换成真实的 LLM 调用和工具调用。7.3 关键节点的提示词设计多 Agent 系统里每个 Agent 的提示词就是它的“岗位说明书”。写得好Agent 各司其职写得差Agent 越界乱来。Researcher 的提示词要点明确搜索范围、要求提取事实而非观点、输出结构化。Outliner 的提示词要点给定资料和主题输出三级大纲每节标注预计字数。Writer 的提示词要点严格按大纲写不要自由发挥如果有修订反馈要针对性修改。Reviewer 的提示词要点从逻辑、事实、语言三个维度审查给出具体修改建议明确说“通过”或“不通过”。提示Reviewer 的提示词里一定要有明确的通过标准否则它会一直挑毛病导致无限修订。我的做法是列出三条硬性标准满足即通过。7.4 效果评估与迭代系统跑起来之后怎么判断好不好我通常从三个维度评估完成率多少比例的请求能正常走完全流程质量分人工抽检给生成的文章打分成本平均每篇文章消耗多少 token、多少时间第一版跑下来完成率大概 70%主要卡在 Reviewer 太严格。调整提示词后升到 90%。质量分从 3.2 升到 4.15 分制。成本方面平均每篇 8 万 token还有优化空间。迭代的方向很明确优化 Reviewer 的判断逻辑给 Writer 加缓存避免重复生成把 Researcher 的搜索并行化。8. 多 Agent 编排的学习路线与进阶方向8.1 从入门到熟练的三阶段如果你刚开始学多 Agent 编排我建议按这个路线走第一阶段跑通 Demo。把 LangGraph 官方示例跑一遍理解 State、Node、Edge 三个概念。这个阶段不要追求复杂能跑通就行。第二阶段复现经典模式。把主管模式、流水线模式、辩论模式各实现一遍理解每种模式的适用场景和坑点。这个阶段要多写代码光看没用。第三阶段做真实项目。找一个自己工作或生活里的真实需求用多 Agent 编排实现。真实项目的复杂度会让你真正理解前面学的所有东西。8.2 值得深入的方向跑通基础之后有几个方向值得深入Agent 记忆怎么设计长期记忆怎么检索怎么遗忘Agent 安全提示词注入防御、权限控制、操作审计多模态编排Agent 处理图像、音频、视频成本优化模型路由、缓存策略、批处理可观测性链路追踪、指标监控、异常告警每个方向都够研究很久。我的建议是先深挖一个方向再横向扩展不要什么都浅尝辄止。8.3 一些个人体会最后分享几点我在实际项目里的体会。第一不要为了多 Agent 而多 Agent。能用单 Agent 解决的别上多 Agent。多 Agent 带来的复杂度是实打实的收益不明显就别上。第二编排逻辑比 Agent 本身更重要。我见过太多项目把精力花在调提示词上结果编排逻辑一塌糊涂。提示词是术编排是道。第三可观测性要一开始就做。别等到出问题才想起来加日志那时候已经晚了。链路追踪、指标监控这些东西越早接入越好。第四成本意识要贯穿始终。多 Agent 系统的 token 消耗很容易失控每次设计都要问自己这一步真的需要调用 LLM 吗能不能用规则替代能不能缓存第五保持简单。我踩过的最大的坑就是过度设计。一开始就想着支持各种复杂场景结果代码写了一堆实际用到的没几个。先做最简单的版本跑通了再逐步加功能。多 Agent 编排这个领域还在快速演进今天的 best practice 明天可能就过时了。但底层的思路——分而治之、状态管理、流程控制——这些是不变的。把这些搞扎实工具怎么变都不慌。 多Agent编排实战：LangGraph核心模式与工程化避坑指南
1. 多 Agent 编排到底在解决什么问题1.1 从单 Agent 到多 Agent 的必然演进先说结论单 Agent 能做的事天花板比大多数人想象的要低得多。我去年帮一个团队做智能客服系统一开始就是单个 Agent 包打天下——理解用户意图、查知识库、调工单接口、生成回复全塞在一个提示词里。前两周跑得挺好到第三周就开始出问题工具调用越来越不稳定上下文越来越长模型开始“忘记”自己该干什么。最典型的一个 bug 是用户问“帮我查一下上个月的订单”Agent 居然去调了退款接口。这不是模型不行而是单 Agent 的认知负荷过载了。一个 Agent 同时承担意图识别、任务规划、工具选择、结果校验、回复生成五个角色就像让一个人同时当产品经理、程序员、测试和运维短期能扛长期必崩。多 Agent 编排的核心思路就是分而治之把一个大任务拆成若干子任务每个子任务交给专门的 Agent 处理Agent 之间通过明确的协议传递信息和状态。这跟微服务架构的思路是一脉相承的——单体应用拆成微服务每个服务只干一件事通过 API 通信。1.2 编排和“堆 Agent”是两回事很多人一听多 Agent第一反应是“那我多开几个 Agent 不就行了”。我见过一个项目开发者开了 8 个 Agent结果比单 Agent 还慢还乱。问题出在没有编排。编排Orchestration这个词来自工作流领域核心含义是定义谁在什么时候做什么、做完之后交给谁。没有编排的多 Agent 就是一群无头苍蝇各自为战互相等待甚至死锁。一个合格的多 Agent 编排系统至少要解决四个问题任务分解大任务怎么拆成子任务拆到什么粒度角色分配每个子任务交给哪个 AgentAgent 的能力边界在哪状态传递Agent 之间怎么传数据传什么格式传多少流程控制串行还是并行失败了怎么重试超时了怎么降级这四个问题不解决Agent 越多越乱。下面这张表是我总结的单 Agent 和多 Agent 的适用边界你可以对照自己的场景判断维度单 Agent 适用多 Agent 适用任务复杂度单一意图3 步以内多意图5 步以上工具数量少于 5 个10 个以上上下文长度单轮对话为主多轮、跨会话错误容忍度低错了重来高可局部重试开发成本低一个提示词搞定高需要编排框架调试难度低日志集中高需要链路追踪1.3 为什么现在谈多 Agent 编排正当时两年前谈多 Agent 编排大家会觉得是屠龙之术——模型能力不够工具生态不成熟编排框架几乎没有。现在情况完全变了。模型侧主流大模型在函数调用、结构化输出、长上下文上的能力已经足够支撑复杂编排。工具侧各种 Agent 框架和编排库层出不穷LangGraph 就是其中比较有代表性的一个。工程侧可观测性工具、链路追踪、状态管理这些配套也慢慢跟上了。更重要的是业务场景开始真正需要多 Agent。比如自动化代码审查需要理解代码、检查规范、生成建议、验证建议四个环节每个环节的提示词和工具集都不一样硬塞进一个 Agent 效果很差。再比如深度研究助手需要搜索、阅读、总结、交叉验证、生成报告这本身就是一条流水线。所以现在学多 Agent 编排不是赶时髦而是场景倒逼。你迟早会遇到单 Agent 搞不定的任务到时候再学就晚了。2. 编排框架选型LangGraph 凭什么值得学2.1 主流编排方案的横向对比在动手之前先搞清楚市面上有哪些编排方案各自适合什么场景。我把常见的几类列出来方案类型代表核心思路适合场景坑点链式编排LangChain LCEL线性管道A 的输出给 B简单流水线分支和循环支持弱图编排LangGraph状态图节点边复杂流程、循环、条件分支学习曲线陡角色编排AutoGen多 Agent 对话协作讨论、辩论容易发散成本高事件编排自研事件总线发布订阅大规模异步调试困难硬编码纯 Pythonif-else 调度流程固定的小项目扩展性差我个人的建议是流程简单用 LCEL流程复杂用 LangGraph需要多 Agent 讨论用 AutoGen规模再大就自研。对于大多数想入门多 Agent 编排的开发者LangGraph 是最佳起点因为它把“图”这个抽象做得足够通用既能表达简单流水线也能表达复杂的状态机。2.2 LangGraph 的核心抽象状态、节点、边LangGraph 的心智模型非常简单就三个概念State状态一个共享的数据结构所有节点都能读写。通常是个字典或 TypedDict。Node节点一个函数接收 State返回 State 的更新。每个节点就是一个 Agent 或一个处理步骤。Edge边定义节点之间的流转关系。可以是固定的A 之后必走 B也可以是条件的根据 State 决定走 B 还是 C。这三样东西组合起来就能表达任意复杂的流程。我画个简单的类比State 是共享内存Node 是函数Edge 是调用关系。如果你写过状态机或者工作流引擎这个概念一秒钟就懂了。LangGraph 相比 LCEL 最大的优势是支持循环。LCEL 是 DAG有向无环图不能回头。但很多 Agent 场景需要循环比如“生成代码 → 测试 → 失败 → 重新生成”这就是一个环。LangGraph 天然支持这种结构。2.3 环境准备Python 安装与依赖管理动手之前先把环境搞干净。我见过太多人因为环境问题卡在第一步这里给一套我常用的流程。Python 版本建议 3.10 以上因为 LangGraph 用了一些新语法特性。安装 Python 本身不复杂官网下载安装包一路下一步就行Windows 记得勾选“Add Python to PATH”。装完之后验证python --version pip --version依赖管理我强烈建议用虚拟环境不要往全局环境里装。用 venv 就行python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate激活之后装依赖pip install langgraph langchain-openai langchain-core如果你需要用到 numpy 做数据处理或者 cv2 做图像处理也一并装上pip install numpy opencv-python注意opencv-python 在某些 Linux 环境下需要额外的系统依赖装不上先看报错信息通常是缺 libGL。Ubuntu 下apt install libgl1就能解决。2.4 一个最小可运行示例光说不练假把式。下面是一个最小的 LangGraph 示例两个节点串行执行from typing import TypedDict from langgraph.graph import StateGraph, END class State(TypedDict): input: str step1_result: str step2_result: str def node_a(state: State) - State: return {step1_result: f处理了: {state[input]}} def node_b(state: State) - State: return {step2_result: f二次处理: {state[step1_result]}} graph StateGraph(State) graph.add_node(a, node_a) graph.add_node(b, node_b) graph.set_entry_point(a) graph.add_edge(a, b) graph.add_edge(b, END) app graph.compile() result app.invoke({input: hello}) print(result)跑通这个示例你就理解了 LangGraph 的基本套路定义 State、写节点函数、连边、编译、调用。后面所有的复杂编排都是在这个骨架上加东西。3. 多 Agent 编排的核心设计模式3.1 主管模式一个大脑指挥多个手脚这是最常用也最容易理解的模式。一个 Supervisor Agent 负责理解任务、分解任务、分派给 Worker AgentWorker 干完活把结果交回来Supervisor 决定下一步。这个模式的好处是控制流清晰所有决策集中在一个地方调试的时候只需要看 Supervisor 的日志。坏处是 Supervisor 容易成为瓶颈任务一多就忙不过来。适用场景任务分解逻辑明确、Worker 职责单一的场合。比如一个内容生产流水线Supervisor 负责拆解“写一篇技术文章”这个任务分给“资料搜集 Agent”“大纲 Agent”“正文 Agent”“校对 Agent”。实现上Supervisor 通常是一个带函数调用能力的 LLM 节点它根据当前 State 决定下一个该谁干。LangGraph 里用条件边来实现def supervisor(state: State) - str: # 根据 state 判断下一步 if not state.get(research_done): return researcher elif not state.get(draft_done): return writer else: return reviewer graph.add_conditional_edges(supervisor, supervisor, { researcher: researcher, writer: writer, reviewer: reviewer, })3.2 流水线模式各司其职顺序推进流水线模式把任务拆成固定顺序的几个阶段每个阶段一个 Agent前一个的输出是后一个的输入。这是最接近传统工作流的模式也最容易理解和实现。好处是可预测性强每个阶段的输入输出格式固定测试起来方便。坏处是灵活性差中间某个阶段出问题整个流程就卡住了。适用场景流程固定、阶段边界清晰的任务。比如文档处理流水线解析 → 分块 → 嵌入 → 检索 → 生成。再比如代码审查流水线拉取代码 → 静态检查 → 逻辑审查 → 生成报告。流水线模式在 LangGraph 里就是简单的 add_edge 串联不需要条件边。但要注意错误处理每个节点都要考虑失败的情况不能让异常直接冒泡把整个图搞崩。3.3 辩论模式多个 Agent 互相挑战这个模式比较有意思。多个 Agent 针对同一个问题给出各自的答案然后互相评论、挑战、修正最后收敛到一个共识。适合需要多角度思考的场景比如方案评审、风险评估。实现上通常是两个或三个 Agent 轮流发言用一个“裁判”Agent 判断是否达成共识。LangGraph 里用循环边实现def should_continue(state: State) - str: if state[round] 3 or state[consensus]: return end return debate graph.add_conditional_edges(judge, should_continue, { debate: debater_a, end: END, })这个模式最大的坑是成本。每轮辩论都要调用多次 LLM轮数一多 token 消耗惊人。我的经验是设置硬性轮数上限同时给裁判 Agent 一个明确的“达成共识”判断标准避免无限循环。3.4 层级模式大团队套小团队当任务规模大到一定程度扁平的结构就不够用了。层级模式把 Agent 组织成树状顶层 Supervisor 管几个中层 Supervisor每个中层 Supervisor 管一组 Worker。这个模式适合超大规模任务比如“分析一家公司的财报”可以拆成“财务数据提取”“行业对比”“风险分析”三个子团队每个子团队内部再细分。代价是复杂度爆炸。层级越深状态传递越麻烦调试越困难。我的建议是层级不要超过三层超过三层说明你的任务拆分有问题应该考虑拆成多个独立的图。4. 状态管理与 Agent 间通信的实操细节4.1 State 设计共享什么隔离什么State 设计是多 Agent 编排里最容易翻车的地方。设计得好Agent 之间配合流畅设计得差要么信息不够用要么状态污染。我的经验法则是共享必要信息隔离中间过程。具体来说所有 Agent 都需要的全局信息放 State比如用户原始输入、任务目标、全局配置单个 Agent 的中间产物不要直接塞进 State而是存到外部文件、数据库State 里只放引用State 的字段要少而精超过 10 个字段就要考虑拆分了LangGraph 的 State 支持 reducer可以定义字段的合并策略。比如多个 Agent 同时往一个列表里追加内容from typing import Annotated from operator import add class State(TypedDict): messages: Annotated[list, add] current_task: str这里的Annotated[list, add]表示这个字段的更新方式是追加而不是覆盖。这个细节很关键不设置的话后一个 Agent 会把前一个的结果覆盖掉。4.2 消息传递结构化还是自然语言Agent 之间传消息有两种风格结构化JSON、字典和自然语言纯文本。两种我都用过各有优劣。结构化消息的好处是解析稳定下游 Agent 不用猜格式。坏处是表达能力受限复杂信息塞不进固定 schema。自然语言消息的好处是灵活坏处是下游解析容易出错。我的实践是混合使用控制信息用结构化内容信息用自然语言。比如{ task_id: t001, status: success, content: 这是 Agent A 生成的正文内容可能很长..., metadata: {tokens: 1234, duration: 2.3} }这样下游 Agent 既能稳定拿到状态又能灵活处理内容。4.3 记忆管理短期、长期、共享Agent 的记忆分三层短期记忆当前任务内的上下文存在 State 里任务结束就丢长期记忆跨任务的知识存在向量数据库或文件里共享记忆多个 Agent 都能访问的公共区域比如一个共享的草稿文档短期记忆最简单State 里放就行。长期记忆需要接向量库LangGraph 支持 checkpointer 机制可以把 State 持久化到 SQLite 或 Postgres。共享记忆比较麻烦需要处理并发读写我的做法是用一个专门的“记忆 Agent”来管理其他 Agent 通过它读写。注意长期记忆不是越多越好。我见过一个项目把所有历史对话都塞进向量库结果检索出来的全是噪音。记忆要有选择地存只存那些对未来任务有价值的结论性信息。4.4 并发控制什么时候该并行多 Agent 不一定非要串行。有些任务可以并行比如“同时搜索三个不同的数据源”并行能大幅缩短总耗时。LangGraph 支持并行节点只要多个节点从同一个节点出发且没有相互依赖就会自动并行执行。但并行有几个坑状态冲突多个节点同时写同一个 State 字段结果不确定。解决方法是给字段加 reducer或者让并行节点写不同的字段。资源竞争并行调用 LLM 会瞬间打满 API 配额需要加限流。错误传播一个并行分支失败其他分支怎么办要么全部回滚要么部分成功。这个要在设计阶段就想清楚。我的建议是默认串行确认无依赖再并行。并行带来的复杂度提升往往超过它节省的时间。5. 常见问题排查与避坑实录5.1 Agent 陷入死循环怎么办这是多 Agent 编排最常见的问题。两个 Agent 互相等待或者一个 Agent 反复调用同一个工具流程永远走不到 END。排查思路分三步看日志确认是哪个节点在重复执行重复的触发条件是什么查条件边条件函数的判断逻辑是不是有漏洞比如某个状态永远为 False加护栏给循环加最大轮数限制超过就强制跳出LangGraph 里可以给 State 加一个计数器class State(TypedDict): loop_count: int def should_continue(state: State) - str: if state[loop_count] 10: return end return continue提示护栏不是万能的它只是防止流程卡死真正的问题还是要从条件逻辑上解决。我踩过的坑是条件函数里用了!而不是导致判断永远为真。5.2 状态污染导致下游 Agent 行为异常状态污染的表现是某个 Agent 突然开始做不属于它职责的事或者输出格式完全不对。原因通常是上游 Agent 往 State 里写了不该写的东西。比如上游 Agent 把“思考过程”也写进了 State下游 Agent 看到一堆无关内容就被带偏了。解决方法是严格定义每个字段的写入者在代码层面做约束。我的做法是给 State 字段加注释标明谁写谁读class State(TypedDict): # 写入: supervisor, 读取: all task_goal: str # 写入: researcher, 读取: writer research_result: str # 写入: writer, 读取: reviewer draft: str这样团队协作的时候谁该写哪个字段一目了然。5.3 Token 消耗失控的排查与优化多 Agent 系统的 token 消耗通常是单 Agent 的 3 到 10 倍因为每个 Agent 都要带上下文还要互相传消息。失控的典型表现是账单突然暴涨。优化手段有几个精简 State只传必要信息大文本存外部压缩历史老消息做摘要不要原样传递缓存结果相同输入直接返回缓存不重复调用选对模型简单任务用小模型复杂任务才用大模型我做过一个对比测试同样的任务优化前消耗 12 万 token优化后降到 3 万效果基本没差别。关键就是别把整个对话历史无脑传给每个 Agent。5.4 常见问题速查表现象可能原因排查方向解决手段流程卡住不动条件边判断错误打印 State 看条件值修正条件逻辑加护栏Agent 输出格式错乱状态污染检查上游写入约束字段写入者Token 消耗暴涨上下文过长统计每次调用 token精简 State压缩历史并行节点结果不一致状态竞争检查并发写入加 reducer 或分离字段工具调用失败率高参数格式不对看工具调用日志加参数校验用结构化输出整体响应慢串行节点太多分析各节点耗时无依赖节点改并行5.5 调试技巧链路追踪怎么做多 Agent 系统的调试比单 Agent 难得多因为一次请求会经过多个节点每个节点都可能出问题。没有链路追踪你根本不知道是哪一步出的错。我的做法是给每个节点加统一的日志装饰器记录输入、输出、耗时、token 消耗import time import functools def trace_node(func): functools.wraps(func) def wrapper(state): start time.time() print(f[{func.__name__}] 输入: {state}) result func(state) print(f[{func.__name__}] 输出: {result}, 耗时: {time.time()-start:.2f}s) return result return wrapper生产环境建议接 LangSmith 或者自建追踪系统把每次调用的链路可视化。这个投入是值得的能省下大量排查时间。6. 从 Demo 到生产多 Agent 系统的工程化6.1 安全边界Agent 能做什么不能做什么Agent 一旦接入真实工具就有了实际操作能力。这时候安全边界必须划清楚。我见过一个 Agent 因为提示词注入把数据库里的数据全删了教训惨痛。几条硬性规则工具白名单只给 Agent 开放必要的工具不要图省事全开参数校验所有工具调用的参数都要校验不能直接透传权限隔离不同 Agent 用不同的凭证最小权限原则操作审计所有工具调用都记日志可追溯注意提示词注入是多 Agent 系统的高危风险。用户输入的内容如果直接进了 Agent 的提示词就可能被利用。防御方法是把用户输入和系统提示词严格隔离用结构化格式传递。6.2 性能优化让多 Agent 跑得更快多 Agent 系统的性能瓶颈通常在两个地方LLM 调用和状态传递。LLM 调用优化能并行的并行能缓存的缓存能用小模型的不用大模型。我做过统计一个典型的多 Agent 流程里60% 的 LLM 调用是可以用小模型替代的成本能降一半以上。状态传递优化State 不要太大大对象存外部。LangGraph 的 checkpointer 会序列化整个 StateState 越大序列化越慢。我见过一个项目 State 里塞了几十 MB 的文本每次节点切换都要序列化一遍慢得离谱。6.3 可观测性生产环境必须有的监控Demo 跑通和生产可用之间差的就是可观测性。生产环境至少要监控这几个指标成功率每次请求是否成功完成耗时分布P50、P95、P99 各是多少Token 消耗按任务、按 Agent 统计工具调用成功率哪个工具最容易失败异常分布哪类错误最多这些指标接上告警出问题第一时间知道。我吃过亏一个 Agent 静默失败了一周才发现用户投诉了一堆。6.4 版本管理与灰度发布Agent 系统的提示词、工具、编排逻辑都会变每次变更都可能影响效果。所以版本管理很重要。我的做法是提示词单独存文件用 git 管理编排逻辑用配置文件描述不改代码就能调整新版本先灰度 10% 流量观察指标再全量这样出问题能快速回滚不至于全量翻车。7. 一个完整的实战案例技术文章生成流水线7.1 需求拆解与 Agent 划分说了这么多理论来个完整的实战案例。需求是输入一个技术主题自动生成一篇 3000 字的技术文章。拆解一下这个任务可以分成四个阶段资料搜集搜索相关资料提取关键信息大纲生成根据资料生成文章大纲正文撰写按大纲逐节写正文校对润色检查逻辑、修正错误、润色语言对应四个 AgentResearcher、Outliner、Writer、Reviewer。用流水线模式串联Reviewer 发现问题可以打回 Writer 重写形成一个带循环的流水线。7.2 核心代码骨架from typing import TypedDict, Annotated from operator import add from langgraph.graph import StateGraph, END class ArticleState(TypedDict): topic: str research: str outline: str draft: str review_feedback: str revision_count: int def researcher(state: ArticleState) - ArticleState: # 调用搜索工具整理资料 return {research: ...} def outliner(state: ArticleState) - ArticleState: # 根据资料生成大纲 return {outline: ...} def writer(state: ArticleState) - ArticleState: # 根据大纲写正文如果有反馈则修订 return {draft: ..., revision_count: state.get(revision_count, 0) 1} def reviewer(state: ArticleState) - ArticleState: # 审查正文给出反馈 return {review_feedback: ...} def should_revise(state: ArticleState) - str: if state[revision_count] 3: return end if 通过 in state[review_feedback]: return end return revise graph StateGraph(ArticleState) graph.add_node(researcher, researcher) graph.add_node(outliner, outliner) graph.add_node(writer, writer) graph.add_node(reviewer, reviewer) graph.set_entry_point(researcher) graph.add_edge(researcher, outliner) graph.add_edge(outliner, writer) graph.add_edge(writer, reviewer) graph.add_conditional_edges(reviewer, should_revise, { revise: writer, end: END, }) app graph.compile()这个骨架跑通之后每个节点的具体实现可以逐步替换成真实的 LLM 调用和工具调用。7.3 关键节点的提示词设计多 Agent 系统里每个 Agent 的提示词就是它的“岗位说明书”。写得好Agent 各司其职写得差Agent 越界乱来。Researcher 的提示词要点明确搜索范围、要求提取事实而非观点、输出结构化。Outliner 的提示词要点给定资料和主题输出三级大纲每节标注预计字数。Writer 的提示词要点严格按大纲写不要自由发挥如果有修订反馈要针对性修改。Reviewer 的提示词要点从逻辑、事实、语言三个维度审查给出具体修改建议明确说“通过”或“不通过”。提示Reviewer 的提示词里一定要有明确的通过标准否则它会一直挑毛病导致无限修订。我的做法是列出三条硬性标准满足即通过。7.4 效果评估与迭代系统跑起来之后怎么判断好不好我通常从三个维度评估完成率多少比例的请求能正常走完全流程质量分人工抽检给生成的文章打分成本平均每篇文章消耗多少 token、多少时间第一版跑下来完成率大概 70%主要卡在 Reviewer 太严格。调整提示词后升到 90%。质量分从 3.2 升到 4.15 分制。成本方面平均每篇 8 万 token还有优化空间。迭代的方向很明确优化 Reviewer 的判断逻辑给 Writer 加缓存避免重复生成把 Researcher 的搜索并行化。8. 多 Agent 编排的学习路线与进阶方向8.1 从入门到熟练的三阶段如果你刚开始学多 Agent 编排我建议按这个路线走第一阶段跑通 Demo。把 LangGraph 官方示例跑一遍理解 State、Node、Edge 三个概念。这个阶段不要追求复杂能跑通就行。第二阶段复现经典模式。把主管模式、流水线模式、辩论模式各实现一遍理解每种模式的适用场景和坑点。这个阶段要多写代码光看没用。第三阶段做真实项目。找一个自己工作或生活里的真实需求用多 Agent 编排实现。真实项目的复杂度会让你真正理解前面学的所有东西。8.2 值得深入的方向跑通基础之后有几个方向值得深入Agent 记忆怎么设计长期记忆怎么检索怎么遗忘Agent 安全提示词注入防御、权限控制、操作审计多模态编排Agent 处理图像、音频、视频成本优化模型路由、缓存策略、批处理可观测性链路追踪、指标监控、异常告警每个方向都够研究很久。我的建议是先深挖一个方向再横向扩展不要什么都浅尝辄止。8.3 一些个人体会最后分享几点我在实际项目里的体会。第一不要为了多 Agent 而多 Agent。能用单 Agent 解决的别上多 Agent。多 Agent 带来的复杂度是实打实的收益不明显就别上。第二编排逻辑比 Agent 本身更重要。我见过太多项目把精力花在调提示词上结果编排逻辑一塌糊涂。提示词是术编排是道。第三可观测性要一开始就做。别等到出问题才想起来加日志那时候已经晚了。链路追踪、指标监控这些东西越早接入越好。第四成本意识要贯穿始终。多 Agent 系统的 token 消耗很容易失控每次设计都要问自己这一步真的需要调用 LLM 吗能不能用规则替代能不能缓存第五保持简单。我踩过的最大的坑就是过度设计。一开始就想着支持各种复杂场景结果代码写了一堆实际用到的没几个。先做最简单的版本跑通了再逐步加功能。多 Agent 编排这个领域还在快速演进今天的 best practice 明天可能就过时了。但底层的思路——分而治之、状态管理、流程控制——这些是不变的。把这些搞扎实工具怎么变都不慌。