LangGraph实战多智能体MAS协作模式——分层团队与主管监督模式设计先说个我自己的体会很多做AI应用的朋友一提到多智能体第一反应是“把任务拆成几步让几个Agent轮流干活”。这个方向不能说错但等系统里的角色超过三四个你就会发现真正的问题不是“怎么让Agent干活”而是“怎么让Agent互相知道在干什么、听谁的、什么时候说完”。我最近在用LangGraph重写项目里那块复杂业务编排逻辑核心就是搭了一套多智能体协作框架分别踩了主管监督模式Supervisor和分层团队模式Hierarchical Teams两条路线。这篇文章把这些实践记录下来适合已经跑过LangChain基础链路、想往多Agent方向推进的开发者也适合正在调研MAS架构方案、犹豫要不要上LangGraph的团队参考。如果你还没接触过LangGraph可以先把它理解成一个专门给语言模型用的“状态机图框架”你定义节点节点里跑Agent或普通函数、定义边边代表流程走向LangGraph负责维护一套共享状态让多个节点之间协调工作。多智能体协作的复杂度恰恰就靠这套显式的图结构来兜住它比裸调LangChain链式调用要可控得多。1. 为什么说单Agent是有天花板的——MAS要解决的真实问题1.1 上下文窗口变成“垃圾场”先聊聊单Agent场景。以前很多业务逻辑直接用一个ReAct模式的Agent包住丢给它一个任务让它自己调用工具、自己写中间结果。任务简单时确实爽但只要任务链条长一点问题立刻暴露——所有中间思考、工具返回、历史对话全都堆在同一个上下文里上下文窗口很快就变成一个“垃圾场”。我举个例子某项目里要Agent完成“读取数据库表结构、生成建表语句、写一段数据校验逻辑、再生成一份说明文档”这四步。单Agent能干但干到第三步时前面两轮的工具返回可能已经占了几千个token而且这些信息它根本用不上了。你还没法把它们扔了因为上下文是连续的一扔就断了逻辑链条。多智能体的第一个价值就在这里上下文隔离。每个Agent只管自己专业范围内的那一段父级只保存必要的结论性消息不会把中间过程的脏数据全部带入下一层。这就像团队里每个人只看自己工位这一块不用把全公司的报表都背下来。1.2 工具权限和责任边界是两回事另一个单Agent的硬伤是工具权限。一个Agent手里如果挂了五六个工具模型每次都要从全量工具列表里做选择。工具一多选错工具的概率就会上升而且很难定位是“模型理解错了”还是“工具描述不清”。多Agent架构真正解决的是把工具权限与责任边界绑定谁负责写代码谁就只看到代码执行工具谁负责检索资料谁就只看到搜索工具。这样一来模型每一步的选择空间被大幅压缩行为可预期性显著提升。我实测过同样一个任务在单Agent下工具误用率可能有百分之二三十拆成带独立工具集的多个Agent后误用率能降到肉眼可见的低水平。2. LangGraph为MAS提供的建模基础StateGraph、状态与路由2.1 节点、边、共享状态是MAS的三块积木LangGraph的核心抽象非常精简就三样东西节点Node、边Edge、共享状态State。你可以把节点理解成“一个函数接收当前状态返回对状态的增量修改”把边理解成“节点执行完之后下一步去哪”把状态理解成“一张不断被更新的工作表”。多智能体协作在这个框架里实现起来特别顺因为每个Agent天然可以封装成一个节点。Agent内部怎么思考、怎么调用工具LangGraph不关心它只需要这个Agent最终往状态里追加一条带有输出的消息。而Agent之间的“交流”根本不是靠消息互相发送而是靠往同一个状态字典里写字段。我用一个生活类比来解释状态就像一个共享的白板每个Agent在白板上写自己的结论下一个Agent只看白板上已有的内容再做决策。白板本身不关心是谁写的只关心内容格式对不对。2.2 三种边的形态决定了MAS的控制流复杂度LangGraph的边分成三种普通边、条件边、结束边。普通边就是“执行完A固定去B”条件边是“执行完A根据某个路由函数的返回结果决定去B还是去C”结束边则是“整个图到这里就停了”。MAS里最常用的是条件边。比如主管节点跑完之后要看主管生成的消息里有没有出现特殊路由标记如果有就去调度对应的工作Agent如果没有说明任务已经完成直接走结束边。这个“路由函数”是整个架构的控制中枢也是主管监督模式的技术底座。2.3 为什么LangGraph适合做MAS而不是自己去写调度器我也见过不少团队自己写一个Agent调度器一个循环不断调用模型解析输出里的“action”字段再根据action去执行对应工具。这套东西在小规模demo阶段能跑但一旦涉及多个Agent之间的复杂依赖代码会迅速失控——你要自己管理状态传递、死循环保护、并发控制、错误恢复工程量不亚于写一个小型工作流引擎。LangGraph把这些东西内置了状态模式自动校验递归深度上限甚至还能按节点粒度做检查点与恢复。我实际用下来重点还是放在业务设计上而不是在调度基建上这大概就是框架的意义。3. 主管监督模式Supervisor设计与实现3.1 模式的核心思想一个调度者多个执行者主管监督模式非常适合“任务类型清晰、但任务归属不确定”的场景。整体结构是一个主管节点Supervisor不直接干活它的工作是接收用户请求判断这个请求该分给哪个工作Agent然后把任务转交出去工作Agent干完活结果回到主管这里主管再判断“是继续交给另一个Agent做下一步还是已经可以回复用户”。我在项目里实现过一套写作辅助的MAS拓扑如下主管Agent负责理解任务类型路由给“写稿”、“翻译”、“审校”三个方向写稿Agent持有文档生成工具翻译Agent持有术语表工具和翻译记忆库工具审校Agent持有拼写检查、风格检查工具用户丢一句“写一篇产品介绍然后翻译成英文最后检查一下有没有语法问题”主管会按顺序把任务依次转发给三个工作Agent而不是自己一把梭。3.2 从底层StateGraph手工搭建理解原理比抄API重要现在LangGraph已经提供了高层封装但我建议先看一眼底层实现你才知道高层API到底帮你做了什么。手工版的核心代码极其精简from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated, Literal import functools # 共享状态messages里存的是所有Agent的交流记录 class TeamState(TypedDict): messages: Annotated[list, operator.add] next: str # 工作Agent的节点函数调用模型追加一条消息即可 def make_agent_node(agent, name): def node(state): result agent.invoke(state) return {messages: [result]} return node # 路由函数读取主管的决策字段决定下一个节点是谁 def supervisor_router(state): return state[next] # 建图写稿-翻译-审校都注册为节点主管节点运行完毕后走条件路由 builder StateGraph(TeamState) builder.add_node(supervisor, supervisor_node) builder.add_node(writer, make_agent_node(writer_agent, writer)) builder.add_node(translator, make_agent_node(translator_agent, translator)) builder.add_node(reviewer, make_agent_node(reviewer_agent, reviewer)) builder.add_edge(supervisor, writer) builder.add_edge(writer, supervisor) builder.add_edge(supervisor, translator) builder.add_edge(translator, supervisor) builder.add_edge(supervisor, reviewer) builder.add_edge(reviewer, supervisor) builder.add_conditional_edges( supervisor, supervisor_router, { writer: writer, translator: translator, reviewer: reviewer, FINISH: END, } )注意这里messages字段用了operator.add做归约器reducer意思是每个Agent返回的消息会被追加到列表尾部而不是覆盖。这是多Agent通信的基础每个Agent都能看到前面所有Agent说过什么。这里supervisor_node内部必须让模型输出一个结构化标记指名下一个执行者是谁。底层实现时通常让模型输出JSON字段里带任务归属和执行说明。3.3 提升开发效率用create_agent和add_conditioned_edge快速搭主管模式从LangGraph 0.2.15左右开始官方推出了面向MAS的高层API我实际项目中搭主管模式基本用这套开发效率高很多from langgraph.prebuilt import create_agent from langgraph.prebuilt.chat_agent_executor import AgentState from langgraph.graph import StateGraph, START, END from langgraph.agents import add_conditioned_edge # 三个工作Agent各挂各的工具互不越权 writer_agent create_agent( llm, tools[write_draft_tool, fetch_product_info_tool], namewriter, system_message你负责撰写产品文档草稿聚焦内容结构与信息准确性。, ) translator_agent create_agent( llm, tools[translation_memory_tool, glossary_tool], nametranslator, system_message你负责中英互译严格遵循术语表输出双语对照。, ) reviewer_agent create_agent( llm, tools[style_check_tool, grammar_check_tool], namereviewer, system_message你负责审查文档质量反馈语法、风格、事实错误。, ) # 主管Agent不挂业务工具只做路由决策 supervisor_agent create_agent( llm, tools[], namesupervisor, system_message( 你是团队主管负责将任务分配给writer、translator、reviewer。 每次分配时在你的回复末尾使用标签 写稿请选择writer翻译请选择translator审校请选择reviewer 如果所有任务已完成选择FINISH。 ), ) # 建图 workflow StateGraph(AgentState) workflow.add_node(supervisor, supervisor_agent) workflow.add_node(writer, writer_agent) workflow.add_node(translator, translator_agent) workflow.add_node(reviewer, reviewer_agent) # 工作Agent干完活必须回到主管由主管决定下一步 for worker_name in [writer, translator, reviewer]: workflow.add_edge(worker_name, supervisor) # 主管节点执行完按模型输出的“路由标签”走对应分支 add_conditioned_edge(workflow, supervisor, [writer, translator, reviewer]) workflow.add_edge(START, supervisor)需要注意的是add_conditioned_edge会在内部自动识别主管Agent输出消息里的next字段LangGraph高层API在Agent内部已经帮你把模型输出解析成了结构化路由信息不需要你自己再写路由函数。3.4 主管模式设计要点工具剥离与路由提示词是成败关键第一个要点的核心原则是主管不要拥有业务工具。我第一版实现里图省事给主管挂了全部工具结果它老是绕过下属自己动手。你可以理解成主管一旦手里有了工具模型天然倾向于“自己干更快”然后它的回复就开始出现工具调用而不是路由指令。后来我把主管的tools设为空列表配合提示词里强调“你只能分配任务不能执行任务”误用率才降下来。第二个要点是路由提示词的明确性。很多踩坑是因为主管的分支标签写得模糊比如只写“你根据任务内容选择合适的人”模型就经常自创标签。我在生产代码里直接规定“如果任务已完成必须输出FINISH”并且每次用统一的格式这样后续做链路追踪也方便。4. 分层团队Hierarchical Teams模式设计与实现4.1 层级结构当监督者本身也需要监督主管监督模式解决的是“一层任务分配”。但真实业务往往更复杂比如一个数据科学团队既有数据分析任务又有文档撰写任务而分析任务本身还要细分为“查数据”、“做图表”、“写结论”三个角色。主管如果直接管所有细分工种它的决策空间会爆炸提示词也会越来越长。分层团队模式就是为这类场景设计的每个团队内部有一个主管不同团队再共享一个更上层的主管。上层主管只管“把任务交给哪个团队”不关心团队内部怎么分工下层主管只管“把任务交给团队里哪个成员”。这样每一层的决策宽度都被限制在很小的范围里提示词清晰路由准确率也会随之提升。我之前在项目里搭过一个“市场调研报告生成系统”拓扑如下顶层主管决定任务属于“数据分析”还是“报告写作”分析团队Team A分析主管决定任务分给“搜索资料”、“数据统计”、“图表生成”搜索Agent持有搜索工具统计Agent持有计算工具图表Agent持有可视化工具写作团队Team B写作主管决定任务分给“内容策划”、“正式撰写”策划Agent持有大纲生成工具撰写Agent持有文档渲染工具4.2 递归建模团队Agent的Input是上一层状态用LangGraph实现分层团队的时候核心技巧是每个团队本身是一个编译好的子图它的输入输出结构必须和上层图兼容。也就是说团队内部虽然有主管、有工作Agent、有自己的内部状态但从上层主管的角度看这个团队就是一个“黑盒Agent”——你给它一个任务消息它还你一个完成结果。这是LangGraph非常优雅的地方一个图可以被当作一个节点嵌入另一个图。代码结构大致这样from langgraph.prebuilt import create_agent, create_team_supervisor from langgraph.graph import StateGraph, START, END # 先定义两个团队的内部状态 class AnalysisTeamState(TypedDict): messages: Annotated[list, operator.add] team_members: list class WritingTeamState(TypedDict): messages: Annotated[list, operator.add] team_members: list # Team A分析团队 analysis_team_agent create_agent( llm, tools[..., analysis_tools], namedata_researcher, system_message你负责搜索并整理数据。, ) analysis_chart_agent create_agent( llm, tools[chart_tool], namechart_designer, system_message你负责生成图表。, ) analysis_supervisor create_team_supervisor( llm, tools[tool for agent in [analysis_team_agent, analysis_chart_agent] for tool in agent.tools], nameanalysis_supervisor, team_members[data_researcher, chart_designer], system_message你是分析团队主管协调数据搜索与图表生成。, ) analysis_graph StateGraph(AnalysisTeamState) analysis_graph.add_node(analysis_supervisor) analysis_graph.add_node(analysis_team_agent) analysis_graph.add_node(analysis_chart_agent) analysis_graph.add_edge(data_researcher, analysis_supervisor) analysis_graph.add_edge(chart_designer, analysis_supervisor) add_conditioned_edge(analysis_graph, analysis_supervisor, [data_researcher, chart_designer]) analysis_graph.add_edge(START, analysis_supervisor) analysis_team analysis_graph.compile() # Team B写作团队结构类似省略中间节点定义 writing_team writing_graph.compile() # 顶层团队把两个团队作为“子Agent”嵌入 class TopTeamState(TypedDict): messages: Annotated[list, operator.add] next: str top_supervisor create_team_supervisor( llm, tools[...], nametop_supervisor, team_members[analysis_team, writing_team], system_message你是总负责人将任务分派给分析团队或写作团队。, ) top_graph StateGraph(TopTeamState) top_graph.add_node(top_supervisor) top_graph.add_node(analysis_team) # 子图嵌入为节点 top_graph.add_node(writing_team) # 子图嵌入为节点 for team_name in [analysis_team, writing_team]: top_graph.add_edge(team_name, top_supervisor) add_conditioned_edge(top_graph, top_supervisor, [analysis_team, writing_team]) top_graph.add_edge(START, top_supervisor) full_app top_graph.compile()注意这里create_team_supervisor会自动给Agent注入team_members列表和路由指令它会用“移交”工具来把控制权从一个团队转移到另一个团队这个工具实际是LangGraph官方封装的。这也解释了为什么叫“分层主管模式”——指令是上下级的控制权是通过工具移交的状态是逐层收集的。4.3 分层设计里最容易被忽略的通信问题踩过一次坑提个醒团队内部的messages与团队外部的messages在物理上是同一份状态列表。也就是说分析团队里“图表设计器”说的话最终会被顶层主管看到。这在多数场景下没问题但也意味着你必须在提示词里明确“团队内部讨论无需向外部汇报的细节就不要输出”否则顶层主管会被噪音干扰。另一个问题是子图之间的数据传递。分析团队产出的是图表文件路径写作团队需要拿到这个路径才能写报告。我的做法是让分析团队的主管在最终汇总消息里明确给出attachment/path/to/chart.png这类结构化字段顶层主管在转发任务给写作团队时把附件信息一并塞到任务消息里。由于顶层主管的上下文里已经包含了分析团队的总结消息这个信息链自然就通了。5. 跑通完整实例参数配置、边界条件与排查方法5.1 路由消息的格式约定提前定死别让模型自由发挥无论主管监督模式还是分层团队模式路由决策都是整个系统里最关键的环节。我在代码里强制要求所有主管节点在生成回复时最后一个内容块必须是{type: route, target: xxx}这种固定格式然后在状态层做一次解析校验解析失败就强制走重试路径。这样做的好处是方便日志追踪每轮路由决策都能记录下来也方便加约束。如果让模型自由发挥文本标签很容易出现大小写不一致、标签拼写错误等情况一旦路由函数匹配不上整个流程就会僵住。5.2 RecursionLimitMAS最常见的隐形杀手多Agent系统比单Agent更容易触碰LangGraph的递归深度上限。因为每次任务在主管和工作Agent之间来回转一次就算两层节点。三层团队结构下一个简简单单的多步任务可能轻松消耗十几次递归。LangGraph默认的递归深度是25次对于主管模式通常够用但对分层团队模式往往不够。我在构建复杂编排时直接把它调到200app workflow.compile() config {recursion_limit: 200, configurable: {thread_id: test_thread_001}} result app.invoke(input, configconfig)判断是否触顶的标准也简单报错信息里出现“RecursionLimit”字样或者运行突然中断。调这个参数的时候留意你用的模型服务商的具体计费逻辑递归越深token消耗越大不是调得越高越好。5.3 前向单元测试用固定输入验证路由正确性MAS比普通Agent链更难调试因为每次模型输出有随机性你很难复现问题。我的建议是把“路由决策”和“执行细节”分离测试先准备一组预定义的任务描述直接调用主管Agent检查它输出的路由目标是否符合预期再分别单独测试各个工作Agent看它们对各自专业任务的执行质量。我建议把这些用例固化成测试脚本每次改动提示词或工具描述后立刻跑一遍。实测下来这个习惯至少帮我提前发现过三层结构里某个团队的成员注册遗漏这种问题在完整链路里往往要调试很久才能定位。6. 复盘分层团队与主管监督模式的最佳适用场景与常见坑6.1 两种模式怎么选——几个判断标准先说结论一层任务分配用主管监督模式任务团队内部还需要再分工的场景用分层团队模式。但实际决策时我还会参考这几个指标。第一看决策宽度。如果主管的直接下属超过五个路由准确率会明显下降。与其把所有角色放在一层里不如按职责归类成几个团队。第二看工具依赖。如果某些工具只在某个子流程里出现把它们封进团队内部实现能避免上层主管为无关工具分散注意力。第三看复用性。分析团队如果既要给报告生成系统用又要给其他业务模块用把它封装成一个独立的可嵌入子图长期看值回票价。6.2 采坑记录三个我交付后仍困扰过的问题第一个坑也是最常见的一个共享状态里messages列表无限膨胀。多Agent之间每轮交互都会追加消息如果任务步骤多状态里的历史消息会积累到惊人的长度。我的处理策略是主管节点在总结完一轮子任务后手动调用一个“压缩”节点把工作Agent的详细输出替换成一条摘要消息。这个操作类似于把对话历史做了摘要换来后续Agent更快的响应速度和更低的token消耗。第二个坑工作Agent返回了“成功”但实际结果缺乏结构校验。比如图表Agent说“我生成了一张图表”但没给附件路径。上层主管无法验证它是否真的干成了。解决方式是给每个工作Agent配备统一的“交付物模板”——提示词里规定“必须输出包含附件路径的JSON”。不过这不是纯流程问题还依赖具体实现细节。第三个坑也是我个人最有体感的监督者模式并不适合所有任务。如果一个任务本身高度线性、每一步的输入强依赖上一步的结果分层团队可能比主管模式更适合——线性流程可以让步骤之间直接连边不需要每步都回到主管绕一圈。主管模式更适合“任务类型可并行判断、依赖关系较弱”的场景否则你会在主管和工作Agent之间来回传递消息白白损耗时间和token。6.3 一点个人体会从项目架构的视角看多智能体系统最大的收益不是“让AI显得更智能”而是让复杂任务的执行过程变得可拆分、可观测、可干预。LangGraph把这些机制落到了状态图这个直观的载体上。分层团队和主管监督两种模式也不是互斥的实际项目往往会混合使用——根子在上层用分层团队控制决策宽度局部在下层用主管监督解决分工协调。建议你从最简单的两层结构开始试跑通以后再往三层扩展别一上来就追求复杂的组织结构。我自己的调试习惯是先固定模型和工具版本把路由测试做扎实再考虑提示词花样。这套思路适合绝大多数业务场景也希望能对正在做MAS方案选型的朋友有点参考价值。