最近我把一个内部数据报告系统从单一 Agent 架构迁到了多 Agent 协作架构用的就是 Supervisor 模式。刚开始我并不认为这是必要动作毕竟单选 Agent 看起来也能解决问题把工具都挂上、把上下文开大、把提示词写长很多场景确实能跑通。但等到任务复杂到一定程度问题就藏不住了——上下文被中间结果塞满工具调用互相干扰一个环节的小错误还会顺着链式调用一路放大。换到 Supervisor 模式之后整体稳定性和可维护性明显上了一个台阶。这篇文章不会只讲概念我会用一个实际的数据分析项目把 Supervisor 模式的角色设计、Agent 配置、任务执行链路、调试经验完整拆开给你一套能直接落地的多 Agent 协作思路。无论你是刚接触 AgentScope 2.0还是已经在写多 Agent 编排层都可以从里面找到能用的东西。整篇文章的核心是回答一个问题如何通过 Supervisor 模式构建一支各司其职的专家团队用最小的调度成本突破单 Agent 的能力天花板。为了方便理解我会先讲清楚为什么需要团队再做配置再跑一次完整的任务最后把最容易踩的坑和优化手段一并交代清楚。1. 单一 Agent 的边界到底卡在哪很多人一上来就陷入一个误区觉得“把模型换成更强的、把上下文加长问题就解决了”。我自己以前也这么想结果模型换了三四轮效果曲线很快就进入了平台期。单一 Agent 的瓶颈不是模型能力本身而是它在一次运行中需要同时处理的变量太多了。1.1 上下文窗口不是万能药大模型的上下文窗口这两年越做越长十万 token、二十万 token 都不稀奇。但窗口大不等于你能往里面塞那么多东西。模型在长上下文里的注意力会衰减这是有论文背书的客观现象信息量超过某个阈值后模型会“迷失在中间”开头和结尾记得住埋在中间的关键断言却容易漏。我实测下来当单个对话里塞进多份数据文件、多轮工具返回结果和几版中间草稿时即使是目前公认很强的模型也会出现“前后矛盾”“引用错误数据”这样的低级失误。更隐蔽的问题是成本。上下文翻倍token 消耗跟着翻倍而且不是线性增长——每次工具调用都会把历史记录重新发给模型调用十次历史记录就被送十次。一个看起来不复杂的单 Agent 任务实际 token 消耗可能是预期的三到五倍。所以与其硬扛上下文不如让每个 Agent 只面对小范围上下文各管一段再通过协作把结果拼起来。这就是 Supervisor 模式存在的第一个理由。1.2 工具链又长又乱单 Agent 反而低效单一 Agent 会把自己暴露在全部工具面前这是性能杀手。做一个数据分析任务你可能要给 Agent 注册数据库查询、Python 执行、文件读写、图表绘制、报告生成五类工具。工具数量一多模型每次选择工具的失误率就会上升而且它很难判断“这类工具到底该在什么时机用”。就算把工具名称和维护文档写得再清楚模型依然会犯一种很典型的错误在只需要“查询数据”的步骤它偏要先生成一段 Python 代码去读 CSV在只需要“画个趋势图”的步骤它反而去 SQL 里折腾了半天。表面上是模型不听话实际上是因为“下一步该干什么”和“下一步该调哪个工具”两个决策边界没有分开。在专家团队里这个问题会被天然稀释。负责数据的 Agent 只看到数据库工具负责报告的 Agent 只看到文本和排版工具工具数量从十来个降到了两三个。决策空间越小模型的选择准确率就越高这也是为什么我倾向于把工具按 Agent 隔离而不是全塞给一个人。1.3 从“对话式”到“协作式”的思维转变单一 Agent 本质上还是“对话式”用户说一句Agent 想半天做一堆事回一段话。整个过程是单线程的中间一旦某一步出错就要从头再来或者让用户手动纠正。协作式的思路完全不同用户面对的不再是一个万能助手而是一个带团队的“主管”。主管收到目标之后把任务拆成子任务分别派给不同的专家 Agent专家各干各的最后主管收口汇总。比如“分析数据并生成图表报告”这个需求在协作式架构里会被拆成“清洗数据”“计算指标”“绘制图表”“撰写文字”“审查质量”五个子任务。这其实是把软件工程里的模块化思想搬到了 Agent 调度层。思维转变之后你会发现整个系统的容错能力也变了。单 Agent 里“一步错步步错”协作式里专家 Agent 失败了主管可以只重派那一个子任务其他结果继续复用。这也是 Supervisor 模式在生产环境里更容易存活的核心原因。2. Supervisor 模式的运行逻辑与设计取舍Supervisor 这个词听起来很高级但落到工程上就几句话的事它负责拆解任务、分配任务、验收结果。它不是来写业务代码的而是来做编排的。2.1 Supervisor 到底管什么调度、决策与仲裁我常用一个比喻Supervisor 是项目经理不是业务骨干。项目经理的第一件事是调度。用户丢来一个目标Supervisor 要判断这个目标需要哪些角色参与每个角色承担什么范围哪些步骤能并行、哪些只能串行。然后是决策。任务执行过程中会出现各种意外某个专家 Agent 返回的结果质量不行某份数据缺失某个子任务超出预期时间。这些情况都需要 Supervisor 做出“继续、重试、换人、降级”的判断。最后是仲裁。不同专家 Agent 给出的结论可能互相矛盾比如数据分析师说“投入产出比高”风险审核专员说“风险不可控”Supervisor 需要根据目标权重做裁决或者生成一个综合性的回答。还有一个常见的误解是 Supervisor 应该直接参与具体内容的生成。其实不需要。Supervisor 如果把精力花在写段落、算数字上它自己的上下文就会被占用调度判断能力反而下降。我的做法是让 Supervisor 只做轻量分析重活全部下放它只需要知道“结果是否完整”“格式是否正确”“要不要退回重做”。2.2 对比其他协作范式Pipeline、Group Chat、Hierarchical 的取舍多 Agent 协作不是只有 Supervisor 一种编排方式但选择哪种取决于你任务的“确定性程度”。Pipeline 模式是固定的流水线A 做完给 BB 做完给 C。它适合流程非常确定、中间环节基本不会变化的场景比如“OCR 识别 → 提取字段 → 入库”。优点是稳定缺点是遇到分支逻辑或不确定性任务时很难写。Group Chat 模式是让多个 Agent 自由讨论。它适合头脑风暴、方案辩论、多角度分析。缺点是容易发散讨论几十轮也收敛不了token 成本极高。我试过一次让三个 Agent 讨论“如何降低客户流失率”效果确实有但到了第 12 轮开始不断重复观点最后还是我手动打断。Hierarchical 模式下 Supervisor 也分多层适合超大组织架构比如你既有战略层 Supervisor又有研发组和商业组的子 Supervisor。缺点也很明显层数多了之后调度链路变长失败概率和延迟都会上升。对比下来单层 Supervisor 模式是“目标明确但路径多变”的这类任务里性价比最高的选择。它比 Pipeline 灵活比 Group Chat 收敛又比两层以上的 Hierarchical 轻量。真实业务里大多数任务——数据分析、客服工单处理、内容生成、代码审查——都符合这个特征。2.3 什么时候不该用 Supervisor说了这么多好处也得泼盆冷水。有些场景用 Supervisor 不但没收益反而添乱。第一个是任务太简单。用户只问一个“今天天气怎么样”你搞一个 Supervisor 带五个专家光调度开销就比答案本身还长。第二个是任务需要高度自由探索。比如“帮我想十个营销创意”这种场景用 Group Chat 让几个 Agent 互相碰撞效果比中央集权式的 Supervisor 好。第三个是任务虽然复杂但单 Agent 借助一份高质量提示词就能解决。比如一个结构化报告生成任务只要输入模板足够清晰单 Agent 也能跑得很好没必要为了“多 Agent”而多 Agent。我自己的选型标准很简单当任务包含多个独立技能域、且每个技能域需要不同工具和知识时用 Supervisor当任务属于单技能域的长链条处理时先用单一 Agent 优化提示词不够再说。别把架构搞复杂方案越简单越容易维护。3. 实战配置基于 AgentScope 2.0 搭一支专家团队概念聊完了进入实操。现在以 AgentScope 2.0 的配置风格为参考演示怎么搭专家团队。代码你可以不逐字照抄重点理解每个字段的含义以及为什么这样配置。3.1 先定角色再写代码专家团队的角色分工我接到一个“把调研数据整理成周报”的需求第一反应不是写代码而是列角色。这个需求需要哪些能力要查询数据、要清洗数据、要算指标、要画图表、要写文字、要检查质量。如果全部塞给一个 Agent工具至少得有七八个拆开之后每个 Agent 只需要两三个工具。我最终定了四个角色DataAgent负责数据库查询、数据清洗、指标计算工具是 query_database 和 clean_dataframe。CodeAgent负责执行 Python 代码绘制图表生成可视化工具是 python_executor。WriterAgent负责基于结构化数据生成报告文本不接触原始数据库。ReviewerAgent负责审查报告质量检查数据引用是否准确、结论是否有依据。角色划分的原则是“技能内聚交互最小”。每个 Agent 的技能要尽可能聚焦不要让 DataAgent 去写报告也不要让 WriterAgent 去碰数据库。Agent 之间的交互全部通过 Supervisor 中转不搞直接通信。这样设计的好处是任何 Agent 出问题我都能快速定位到具体角色而不是在两个 Agent 的私聊记录里翻半天。3.2 构建 Agent 配置与工具注册把工具限定在职责范围内角色清单定了之后我对照着把它们变成配置代码。这里用 AgentScope 2.0 常见的注册方式做演示Python 伪代码如下from agentscope import Agent, Tool # 数据专家 data_agent Agent( nameDataAgent, role数据查询与清洗专家, system_prompt( 你负责查询数据库、清洗数据、计算关键指标。 输出必须是结构化 JSON包含指标名和数值。 ), tools[ Tool(query_database, params{sql: str}), Tool(clean_dataframe, params{rule: str}), ], modelqwen-max, ) # 代码执行专家 code_agent Agent( nameCodeAgent, rolePython 代码执行与图表生成专家, system_prompt( 你负责编写并执行 Python 代码生成图表。 只能输出代码执行结果和图表保存路径。 ), tools[ Tool(python_executor, params{code: str, timeout: 30}), ], modelqwen-max, ) # 报告撰写专家 writer_agent Agent( nameWriterAgent, role数据报告撰写专家, system_prompt( 你负责把结构化数据转换成逻辑清晰的中文报告。 不得创造数据所有数字必须来自输入。 ), tools[ Tool(markdown_render, params{content: str}), ], modelqwen-max, )这套配置的关键点不在字段名而在于两个设计细节。第一个是给 Agent 的 system_prompt 里写清楚“你只能做什么、绝不能做什么”比如 WriterAgent 被明确禁止创造数据这就减少了数据幻觉。第二个是每个 Agent 的工具数量被压缩到了 1~2 个模型做工具选择的压力会小很多。3.3 Supervisor 的提示词与任务分发逻辑Supervisor 的配置比普通 Agent 多了一层“成员列表”和“分发策略”。核心提示词我写了大概两百字重点不是文采而是把流程说死让模型知道什么时候该做什么。supervisor SupervisorAgent( nameSupervisor, members[data_agent, code_agent, writer_agent], system_prompt( 你是一个多智能体团队的主管。团队成员包括 DataAgent数据查询与清洗、CodeAgent代码执行与图表、 WriterAgent报告撰写。 当收到用户目标时你必须 1. 拆解为子任务每个子任务必须匹配一个或多个成员 2. 将子任务按依赖关系排序 3. 等待成员返回结果并对结果做质量判断 4. 如果结果不合格向成员反馈原因并要求重做最多重试两次 5. 汇总所有结果生成最终回答确保引用真实返回的数据。 不要替成员完成他们的工作。 ), task_strategydependency_graph, # 按依赖关系分发 max_retries2, )任务分发逻辑上我用的是“先拆成依赖图再按拓扑序下发”。比如“画图表”必须等“算指标”完成“写报告”必须等“画图表”完成这些依赖关系写死在任务定义里。如果两个子任务没有依赖关系我会把它们并行下发给不同 Agent减少整体延迟。这里的 task_strategy 只是示意强调的是分发顺序不能乱。还有一个容易被忽略的配置项是 max_retries。我把它设置为 2是为了避免整个流程无限重试。后面踩坑部分我会专门展开这里先记住这句话多 Agent 系统一定要有一个“强行叫停”的机制。3.4 多模态能力在哪里介入输入解析与工具链很多人提到 Agent 多模态第一反应是“模型能不能看图”。在实际工程里多模态更常见的是输入解析和工具链的配合用户上传了一张截图、一只 PDF、一个 Excel系统要先想办法把这些非文本内容转成 Agent 可处理的结构化信息然后才能进入后续的协作流程。我在这个项目里加了一个小设计在 Supervisor 之前放一个“输入归一化层”。用户上传的 Excel 会被解析成 DataFrame 摘要PDF 会被抽取成文本段落截图会自动走一次 OCR 或者视觉模型提取关键字段然后再进入 Agent 团队。这个归一化层本质上是把多模态输入统一转成了文本和结构化数据的组合让下游的 DataAgent 不用操心“怎么读 PDF”这种脏活。这样设计的另一个好处是如果以后换成只能处理文本的模型整套架构也不受影响。多模态能力的边界不是关于模型“能不能看图”而是看整个团队“能不能把非结构化信息变成决策可用的结构”。在这个团队里DataAgent 处理表格、CodeAgent 处理图表、WriterAgent 处理文字已经是一种很务实的多模态分工。4. 让任务真正跑起来一次完整的多 Agent 执行流程配置搭好之后接下来要跑一遍真实流程。我用“分析这些调研数据生成一份包含图表和结论的周报”这个需求当例子带你走一遍从拆解到汇总的完整链路。4.1 从用户请求到任务拆解一次实际请求全过程Supervisor 收到用户请求后会先做意图识别和任务拆解。别急着让模型大开脑洞先用明确的 Prompt 约束它把子任务清单写成一个标准结构。我期望的拆解结果大致是这个样子任务编号负责人任务内容前置依赖T1DataAgent清洗调研数据去除空值和异常值无T2DataAgent计算关键指标如平均分、同比变化T1T3CodeAgent根据指标生成趋势图和对比图T2T4WriterAgent基于 T2 和 T3 的结果生成周报文字T2、T3T5ReviewerAgent审查最终报告的数据准确性和逻辑T4这个表格看起来很直白但真正考验 Supervisor 的地方是“怎么把模糊的用户需求变成精确的子任务”。比如“包含图表”这个指令Supervisor 需要判断出这对应的是 CodeAgent 的绘图能力而不是让 WriterAgent 在文本里画个假图表。为了让模型少犯这种错我会在 system_prompt 里写明每个 Agent 的交付物类型并给一个任务清单模板。4.2 专家 Agent 的执行与结果回传按契约交付每个专家 Agent 执行完任务后不是把一段话随便丢回来而是要按约定好的格式回传结果。如果格式不固定Supervisor 很难判断“这个结果到底能不能用”。我给所有 Agent 定了一个统一的交付结构{ task_id: T2, status: success, result: { metrics: { average_score: 4.6, growth_rate: 12% } }, error: null, metadata: { execution_time_ms: 3200, model: qwen-max } }status 字段是最重要的。只有 success 的结果Supervisor 才会往下游分发如果是 failed 或者 partialSupervisor 会读取 error 字段决定是重试还是换一个 Agent。result 字段的内容则根据角色不同而不同DataAgent 返回指标字典CodeAgent 返回图表路径WriterAgent 返回报告 Markdown。规范化输出还有一个隐形好处调试的时候你可以直接用程序解析日志来判断哪个环节出了问题而不是让一个 LLM 去理解另一个 LLM 的输出里有什么猫腻。我把这些 Agent 的输出全部落盘成了 JSON后续排查问题省了很多事。4.3 收口与汇总Supervisor 如何聚合结果并做第二轮调度所有子任务都成功之后Supervisor 进入汇总阶段。这里有一个很容易踩的坑直接拿所有专家结果拼成一个大字符串发给模型让它“写最终答案”。这样做的后果是上下文爆炸而且会出现“总结没有引用专家数据”的情况。我更推荐的做法是Supervisor 在汇总时先做信息压缩。它读取 DataAgent 返回的指标、CodeAgent 返回的图表路径、WriterAgent 返回的报告文本把这些信息整理成一个简明的“材料清单”再基于这个清单生成最终周报。材料清单里可以包括“核心结论”“图表路径”“待审查风险”“用户原始需求”四类内容。信息压缩让无关细节被过滤掉模型生成最终交付物时不会因为上下文过长而出错。另外汇总不是只做一次。ReviewerAgent 如果发现初稿里“结论缺少数据支撑”会把缺陷反馈给 Supervisor。Supervisor 这时要做第二轮调度把缺陷描述附在任务里重新分派给对应的专家 Agent 修改。这个“检查-反馈-再调度”循环是整个 Supervisor 模式最能体现价值的地方。你可以把 ReviewerAgent 当成团队里的测试岗位它不直接写报告但它的反馈决定了报告能不能发出去。5. 调试与稳定性我在实战中踩过的坑多 Agent 系统最大的问题不是“跑不起来”而是“跑起来之后怎么稳定不出错”。这一章我挑几个真实的坑摊开讲希望你不用再走一遍。5.1 Agent 之间的“脏数据”污染一次典型事故复盘我第一次把这套系统上线时遇到过一个问题WriterAgent 生成的报告里某个数据比 DataAgent 给出的原始指标多了整整 10 倍。查了半天发现是 DataAgent 在返回结果时顺手把一段错误的状态日志也塞进了 result.content 字段。下游 WriterAgent 读到了这段日志把它当成了真实数据最后逐字写进了报告。这就是典型的脏数据污染。根因很简单专家 Agent 的输出没有做严格的 schema 校验带格式的日志混进了业务数据。修复办法也很粗暴在 DataAgent 和 WriterAgent 之间加一个校验器result.content 只允许包含 JSON 格式的指标对象其他一律丢弃。从那以后我再也不相信任何 Agent 会“自觉”遵守输出格式而是要写一层代码做强制约束。经验总结在多 Agent 系统里接口规范和你企业内部微服务之间的契约一样重要。每个 Agent 的输入输出都要有类型定义、有校验逻辑而不是让下游 Agent 用大模型能力去“猜”。5.2 死循环、重复调用与超时治理另一个高频问题是死循环。Supervisor 把任务派给 DataAgentDataAgent 返回了一个格式错误的结果Supervisor 要求重做DataAgent 又返回格式错误如此反复。如果没有重试限制这个循环会一直跑到预算耗尽。我在这里用了三招。第一招是在 Supervisor 上设置 max_retries2达到上限后直接标记任务失败不再继续尝试。第二招是给每个子任务设置超时时间超过 30 秒没返回就直接判定失败避免个别 Agent 因为模型调用阻塞而拖垮整体流程。第三招是设置金融预算钟每次调用之前检查当前 token 消耗超过预算就降级处理比如把任务回退给单一 Agent 用简单模式完成。这三招放在一起整个系统才算有了“熔断”能力。一个稳定的多 Agent 系统不是保证每一步都不出错而是保证出错之后能快速停止、快速恢复不让个别异常拖垮全局。5.3 如何验证专家 Agent 真的“专业”最后一个坑最隐蔽如何确定你的专家 Agent 真的有专家水平而不是表面意义上做得“像模像样”。如果只是拿一两个例子人工看一遍很可能得出“效果不错”的结论一旦放开真实流量各种幻觉就冒出来了。我的做法是建立一个小型回归测试集。找 20 到 50 个历史真实请求把预期结果写成结构化标签比如“结论是否引用了 DataAgent 返回的指标”“报告里是否存在虚构数据”“图表路径是否真实存在”。每次修改模型、提示词或工具定义之后跑一遍测试集统计通过率。还有一项更轻量的冒烟测试故意给某个专家 Agent 一个不完整的数据集看它是否会“编造”出缺失的数据。很多 Agent 在数据不足时为了显得专业会无中生有捏造一个数字这种问题只有通过针对性测试才能暴露。我把这个测试写成了固定用例每次上线前必跑发现一次就调整一次提示词。6. 进阶优化思路从能跑到跑好当你的 Supervisor 团队能稳定跑通一天之后就可以开始琢磨优化了。优化不是说模型换得更强而是让系统在成本、响应速度、可扩展性上都能适应生产要求。6.1 记忆与状态管理全局状态跟着 Supervisor 走多 Agent 系统里的“记忆”很容易被过度设计。一开始我试图让每个 Agent 都有自己的长期记忆模块结果发现维护成本极高每个 Agent 记了一堆和当前任务无关的历史反而干扰判断。后来我定了一个原则全局状态只归 Supervisor 持有专家 Agent 只有任务级临时记忆。Supervisor 用一个轻量的向量库存“用户偏好”“项目背景”“历史决策原因”每次派发任务时把相关记忆摘录出来放进子任务上下文。专家 Agent 的上下文只在单个任务周期内有效任务结束就丢。这样既保留了“团队记得住以前聊过什么”的能力又不会让每个专家的上下文无限膨胀。6.2 成本控制上下文裁剪与模型分级多 Agent 模式和单 Agent 相比token 消耗天然会更高因为同样一个信息可能要转发好几轮。直接的办法是上下文裁剪。比如派发给 DataAgent 的任务只带上相关字段名和数据筛选条件不把整份 Excel 描述全塞进去派发给 WriterAgent 的任务只带结构化指标不附带原始查询日志。更进一步的玩法是模型分级。Supervisor 的调度和意图识别用便宜的轻量模型比如 qwen-turbo 级别专家 Agent 负责产出内容和执行代码时再上更强模型比如 qwen-max 级别。这样能省不少钱而且质量不会明显下降因为拆解任务这件事本身不需要太强的推理能力真正烧脑的是专家干活。我还在 Supervisor 层的提示词里强制要求“不要重复传输已经在上一轮出现过的数据”只传关键摘要和路径。一开始模型经常忽略但配合输出校验器强制过滤后整体 token 消耗下降了约 40%。6.3 从 Demo 到生产灰度发布与可观测性最后想聊的是把 Supervisor 模式推到生产环境时容易漏掉的一环可观测性。多 Agent 系统比单 Agent 系统难定位问题得多因为一次用户请求可能会触发十几个模型调用和几十次工具执行任何一个环节都可能出问题。我会在每次请求开始时生成一个 trace_id贯穿整个调度链路然后把 Supervisor 的每次决策、专家 Agent 的每次输入输出、每个工具的执行时间都记录到日志系统。用不用 AgentScope 自带的可视化组件都可以核心是日志结构要统一、带 trace_id、有耗时和 token 数。有了这些基础才能做灰度发布先让 5% 的流量走新架构对比关键指标确认无误后再逐步放大。我的建议是先小范围试点。不要一上来就给 Supervisor 配八个专家 Agent先用“一个 Supervisor 两个专家 Agent”跑一个小业务把日志、监控、重试机制全部跑顺再慢慢扩角色。没有可观测性之前多 Agent 系统就是个黑盒出了问题只能抓瞎把这层地基打牢后面加多少 Agent 都不慌。 Supervisor模式：多Agent协作架构实战解析
最近我把一个内部数据报告系统从单一 Agent 架构迁到了多 Agent 协作架构用的就是 Supervisor 模式。刚开始我并不认为这是必要动作毕竟单选 Agent 看起来也能解决问题把工具都挂上、把上下文开大、把提示词写长很多场景确实能跑通。但等到任务复杂到一定程度问题就藏不住了——上下文被中间结果塞满工具调用互相干扰一个环节的小错误还会顺着链式调用一路放大。换到 Supervisor 模式之后整体稳定性和可维护性明显上了一个台阶。这篇文章不会只讲概念我会用一个实际的数据分析项目把 Supervisor 模式的角色设计、Agent 配置、任务执行链路、调试经验完整拆开给你一套能直接落地的多 Agent 协作思路。无论你是刚接触 AgentScope 2.0还是已经在写多 Agent 编排层都可以从里面找到能用的东西。整篇文章的核心是回答一个问题如何通过 Supervisor 模式构建一支各司其职的专家团队用最小的调度成本突破单 Agent 的能力天花板。为了方便理解我会先讲清楚为什么需要团队再做配置再跑一次完整的任务最后把最容易踩的坑和优化手段一并交代清楚。1. 单一 Agent 的边界到底卡在哪很多人一上来就陷入一个误区觉得“把模型换成更强的、把上下文加长问题就解决了”。我自己以前也这么想结果模型换了三四轮效果曲线很快就进入了平台期。单一 Agent 的瓶颈不是模型能力本身而是它在一次运行中需要同时处理的变量太多了。1.1 上下文窗口不是万能药大模型的上下文窗口这两年越做越长十万 token、二十万 token 都不稀奇。但窗口大不等于你能往里面塞那么多东西。模型在长上下文里的注意力会衰减这是有论文背书的客观现象信息量超过某个阈值后模型会“迷失在中间”开头和结尾记得住埋在中间的关键断言却容易漏。我实测下来当单个对话里塞进多份数据文件、多轮工具返回结果和几版中间草稿时即使是目前公认很强的模型也会出现“前后矛盾”“引用错误数据”这样的低级失误。更隐蔽的问题是成本。上下文翻倍token 消耗跟着翻倍而且不是线性增长——每次工具调用都会把历史记录重新发给模型调用十次历史记录就被送十次。一个看起来不复杂的单 Agent 任务实际 token 消耗可能是预期的三到五倍。所以与其硬扛上下文不如让每个 Agent 只面对小范围上下文各管一段再通过协作把结果拼起来。这就是 Supervisor 模式存在的第一个理由。1.2 工具链又长又乱单 Agent 反而低效单一 Agent 会把自己暴露在全部工具面前这是性能杀手。做一个数据分析任务你可能要给 Agent 注册数据库查询、Python 执行、文件读写、图表绘制、报告生成五类工具。工具数量一多模型每次选择工具的失误率就会上升而且它很难判断“这类工具到底该在什么时机用”。就算把工具名称和维护文档写得再清楚模型依然会犯一种很典型的错误在只需要“查询数据”的步骤它偏要先生成一段 Python 代码去读 CSV在只需要“画个趋势图”的步骤它反而去 SQL 里折腾了半天。表面上是模型不听话实际上是因为“下一步该干什么”和“下一步该调哪个工具”两个决策边界没有分开。在专家团队里这个问题会被天然稀释。负责数据的 Agent 只看到数据库工具负责报告的 Agent 只看到文本和排版工具工具数量从十来个降到了两三个。决策空间越小模型的选择准确率就越高这也是为什么我倾向于把工具按 Agent 隔离而不是全塞给一个人。1.3 从“对话式”到“协作式”的思维转变单一 Agent 本质上还是“对话式”用户说一句Agent 想半天做一堆事回一段话。整个过程是单线程的中间一旦某一步出错就要从头再来或者让用户手动纠正。协作式的思路完全不同用户面对的不再是一个万能助手而是一个带团队的“主管”。主管收到目标之后把任务拆成子任务分别派给不同的专家 Agent专家各干各的最后主管收口汇总。比如“分析数据并生成图表报告”这个需求在协作式架构里会被拆成“清洗数据”“计算指标”“绘制图表”“撰写文字”“审查质量”五个子任务。这其实是把软件工程里的模块化思想搬到了 Agent 调度层。思维转变之后你会发现整个系统的容错能力也变了。单 Agent 里“一步错步步错”协作式里专家 Agent 失败了主管可以只重派那一个子任务其他结果继续复用。这也是 Supervisor 模式在生产环境里更容易存活的核心原因。2. Supervisor 模式的运行逻辑与设计取舍Supervisor 这个词听起来很高级但落到工程上就几句话的事它负责拆解任务、分配任务、验收结果。它不是来写业务代码的而是来做编排的。2.1 Supervisor 到底管什么调度、决策与仲裁我常用一个比喻Supervisor 是项目经理不是业务骨干。项目经理的第一件事是调度。用户丢来一个目标Supervisor 要判断这个目标需要哪些角色参与每个角色承担什么范围哪些步骤能并行、哪些只能串行。然后是决策。任务执行过程中会出现各种意外某个专家 Agent 返回的结果质量不行某份数据缺失某个子任务超出预期时间。这些情况都需要 Supervisor 做出“继续、重试、换人、降级”的判断。最后是仲裁。不同专家 Agent 给出的结论可能互相矛盾比如数据分析师说“投入产出比高”风险审核专员说“风险不可控”Supervisor 需要根据目标权重做裁决或者生成一个综合性的回答。还有一个常见的误解是 Supervisor 应该直接参与具体内容的生成。其实不需要。Supervisor 如果把精力花在写段落、算数字上它自己的上下文就会被占用调度判断能力反而下降。我的做法是让 Supervisor 只做轻量分析重活全部下放它只需要知道“结果是否完整”“格式是否正确”“要不要退回重做”。2.2 对比其他协作范式Pipeline、Group Chat、Hierarchical 的取舍多 Agent 协作不是只有 Supervisor 一种编排方式但选择哪种取决于你任务的“确定性程度”。Pipeline 模式是固定的流水线A 做完给 BB 做完给 C。它适合流程非常确定、中间环节基本不会变化的场景比如“OCR 识别 → 提取字段 → 入库”。优点是稳定缺点是遇到分支逻辑或不确定性任务时很难写。Group Chat 模式是让多个 Agent 自由讨论。它适合头脑风暴、方案辩论、多角度分析。缺点是容易发散讨论几十轮也收敛不了token 成本极高。我试过一次让三个 Agent 讨论“如何降低客户流失率”效果确实有但到了第 12 轮开始不断重复观点最后还是我手动打断。Hierarchical 模式下 Supervisor 也分多层适合超大组织架构比如你既有战略层 Supervisor又有研发组和商业组的子 Supervisor。缺点也很明显层数多了之后调度链路变长失败概率和延迟都会上升。对比下来单层 Supervisor 模式是“目标明确但路径多变”的这类任务里性价比最高的选择。它比 Pipeline 灵活比 Group Chat 收敛又比两层以上的 Hierarchical 轻量。真实业务里大多数任务——数据分析、客服工单处理、内容生成、代码审查——都符合这个特征。2.3 什么时候不该用 Supervisor说了这么多好处也得泼盆冷水。有些场景用 Supervisor 不但没收益反而添乱。第一个是任务太简单。用户只问一个“今天天气怎么样”你搞一个 Supervisor 带五个专家光调度开销就比答案本身还长。第二个是任务需要高度自由探索。比如“帮我想十个营销创意”这种场景用 Group Chat 让几个 Agent 互相碰撞效果比中央集权式的 Supervisor 好。第三个是任务虽然复杂但单 Agent 借助一份高质量提示词就能解决。比如一个结构化报告生成任务只要输入模板足够清晰单 Agent 也能跑得很好没必要为了“多 Agent”而多 Agent。我自己的选型标准很简单当任务包含多个独立技能域、且每个技能域需要不同工具和知识时用 Supervisor当任务属于单技能域的长链条处理时先用单一 Agent 优化提示词不够再说。别把架构搞复杂方案越简单越容易维护。3. 实战配置基于 AgentScope 2.0 搭一支专家团队概念聊完了进入实操。现在以 AgentScope 2.0 的配置风格为参考演示怎么搭专家团队。代码你可以不逐字照抄重点理解每个字段的含义以及为什么这样配置。3.1 先定角色再写代码专家团队的角色分工我接到一个“把调研数据整理成周报”的需求第一反应不是写代码而是列角色。这个需求需要哪些能力要查询数据、要清洗数据、要算指标、要画图表、要写文字、要检查质量。如果全部塞给一个 Agent工具至少得有七八个拆开之后每个 Agent 只需要两三个工具。我最终定了四个角色DataAgent负责数据库查询、数据清洗、指标计算工具是 query_database 和 clean_dataframe。CodeAgent负责执行 Python 代码绘制图表生成可视化工具是 python_executor。WriterAgent负责基于结构化数据生成报告文本不接触原始数据库。ReviewerAgent负责审查报告质量检查数据引用是否准确、结论是否有依据。角色划分的原则是“技能内聚交互最小”。每个 Agent 的技能要尽可能聚焦不要让 DataAgent 去写报告也不要让 WriterAgent 去碰数据库。Agent 之间的交互全部通过 Supervisor 中转不搞直接通信。这样设计的好处是任何 Agent 出问题我都能快速定位到具体角色而不是在两个 Agent 的私聊记录里翻半天。3.2 构建 Agent 配置与工具注册把工具限定在职责范围内角色清单定了之后我对照着把它们变成配置代码。这里用 AgentScope 2.0 常见的注册方式做演示Python 伪代码如下from agentscope import Agent, Tool # 数据专家 data_agent Agent( nameDataAgent, role数据查询与清洗专家, system_prompt( 你负责查询数据库、清洗数据、计算关键指标。 输出必须是结构化 JSON包含指标名和数值。 ), tools[ Tool(query_database, params{sql: str}), Tool(clean_dataframe, params{rule: str}), ], modelqwen-max, ) # 代码执行专家 code_agent Agent( nameCodeAgent, rolePython 代码执行与图表生成专家, system_prompt( 你负责编写并执行 Python 代码生成图表。 只能输出代码执行结果和图表保存路径。 ), tools[ Tool(python_executor, params{code: str, timeout: 30}), ], modelqwen-max, ) # 报告撰写专家 writer_agent Agent( nameWriterAgent, role数据报告撰写专家, system_prompt( 你负责把结构化数据转换成逻辑清晰的中文报告。 不得创造数据所有数字必须来自输入。 ), tools[ Tool(markdown_render, params{content: str}), ], modelqwen-max, )这套配置的关键点不在字段名而在于两个设计细节。第一个是给 Agent 的 system_prompt 里写清楚“你只能做什么、绝不能做什么”比如 WriterAgent 被明确禁止创造数据这就减少了数据幻觉。第二个是每个 Agent 的工具数量被压缩到了 1~2 个模型做工具选择的压力会小很多。3.3 Supervisor 的提示词与任务分发逻辑Supervisor 的配置比普通 Agent 多了一层“成员列表”和“分发策略”。核心提示词我写了大概两百字重点不是文采而是把流程说死让模型知道什么时候该做什么。supervisor SupervisorAgent( nameSupervisor, members[data_agent, code_agent, writer_agent], system_prompt( 你是一个多智能体团队的主管。团队成员包括 DataAgent数据查询与清洗、CodeAgent代码执行与图表、 WriterAgent报告撰写。 当收到用户目标时你必须 1. 拆解为子任务每个子任务必须匹配一个或多个成员 2. 将子任务按依赖关系排序 3. 等待成员返回结果并对结果做质量判断 4. 如果结果不合格向成员反馈原因并要求重做最多重试两次 5. 汇总所有结果生成最终回答确保引用真实返回的数据。 不要替成员完成他们的工作。 ), task_strategydependency_graph, # 按依赖关系分发 max_retries2, )任务分发逻辑上我用的是“先拆成依赖图再按拓扑序下发”。比如“画图表”必须等“算指标”完成“写报告”必须等“画图表”完成这些依赖关系写死在任务定义里。如果两个子任务没有依赖关系我会把它们并行下发给不同 Agent减少整体延迟。这里的 task_strategy 只是示意强调的是分发顺序不能乱。还有一个容易被忽略的配置项是 max_retries。我把它设置为 2是为了避免整个流程无限重试。后面踩坑部分我会专门展开这里先记住这句话多 Agent 系统一定要有一个“强行叫停”的机制。3.4 多模态能力在哪里介入输入解析与工具链很多人提到 Agent 多模态第一反应是“模型能不能看图”。在实际工程里多模态更常见的是输入解析和工具链的配合用户上传了一张截图、一只 PDF、一个 Excel系统要先想办法把这些非文本内容转成 Agent 可处理的结构化信息然后才能进入后续的协作流程。我在这个项目里加了一个小设计在 Supervisor 之前放一个“输入归一化层”。用户上传的 Excel 会被解析成 DataFrame 摘要PDF 会被抽取成文本段落截图会自动走一次 OCR 或者视觉模型提取关键字段然后再进入 Agent 团队。这个归一化层本质上是把多模态输入统一转成了文本和结构化数据的组合让下游的 DataAgent 不用操心“怎么读 PDF”这种脏活。这样设计的另一个好处是如果以后换成只能处理文本的模型整套架构也不受影响。多模态能力的边界不是关于模型“能不能看图”而是看整个团队“能不能把非结构化信息变成决策可用的结构”。在这个团队里DataAgent 处理表格、CodeAgent 处理图表、WriterAgent 处理文字已经是一种很务实的多模态分工。4. 让任务真正跑起来一次完整的多 Agent 执行流程配置搭好之后接下来要跑一遍真实流程。我用“分析这些调研数据生成一份包含图表和结论的周报”这个需求当例子带你走一遍从拆解到汇总的完整链路。4.1 从用户请求到任务拆解一次实际请求全过程Supervisor 收到用户请求后会先做意图识别和任务拆解。别急着让模型大开脑洞先用明确的 Prompt 约束它把子任务清单写成一个标准结构。我期望的拆解结果大致是这个样子任务编号负责人任务内容前置依赖T1DataAgent清洗调研数据去除空值和异常值无T2DataAgent计算关键指标如平均分、同比变化T1T3CodeAgent根据指标生成趋势图和对比图T2T4WriterAgent基于 T2 和 T3 的结果生成周报文字T2、T3T5ReviewerAgent审查最终报告的数据准确性和逻辑T4这个表格看起来很直白但真正考验 Supervisor 的地方是“怎么把模糊的用户需求变成精确的子任务”。比如“包含图表”这个指令Supervisor 需要判断出这对应的是 CodeAgent 的绘图能力而不是让 WriterAgent 在文本里画个假图表。为了让模型少犯这种错我会在 system_prompt 里写明每个 Agent 的交付物类型并给一个任务清单模板。4.2 专家 Agent 的执行与结果回传按契约交付每个专家 Agent 执行完任务后不是把一段话随便丢回来而是要按约定好的格式回传结果。如果格式不固定Supervisor 很难判断“这个结果到底能不能用”。我给所有 Agent 定了一个统一的交付结构{ task_id: T2, status: success, result: { metrics: { average_score: 4.6, growth_rate: 12% } }, error: null, metadata: { execution_time_ms: 3200, model: qwen-max } }status 字段是最重要的。只有 success 的结果Supervisor 才会往下游分发如果是 failed 或者 partialSupervisor 会读取 error 字段决定是重试还是换一个 Agent。result 字段的内容则根据角色不同而不同DataAgent 返回指标字典CodeAgent 返回图表路径WriterAgent 返回报告 Markdown。规范化输出还有一个隐形好处调试的时候你可以直接用程序解析日志来判断哪个环节出了问题而不是让一个 LLM 去理解另一个 LLM 的输出里有什么猫腻。我把这些 Agent 的输出全部落盘成了 JSON后续排查问题省了很多事。4.3 收口与汇总Supervisor 如何聚合结果并做第二轮调度所有子任务都成功之后Supervisor 进入汇总阶段。这里有一个很容易踩的坑直接拿所有专家结果拼成一个大字符串发给模型让它“写最终答案”。这样做的后果是上下文爆炸而且会出现“总结没有引用专家数据”的情况。我更推荐的做法是Supervisor 在汇总时先做信息压缩。它读取 DataAgent 返回的指标、CodeAgent 返回的图表路径、WriterAgent 返回的报告文本把这些信息整理成一个简明的“材料清单”再基于这个清单生成最终周报。材料清单里可以包括“核心结论”“图表路径”“待审查风险”“用户原始需求”四类内容。信息压缩让无关细节被过滤掉模型生成最终交付物时不会因为上下文过长而出错。另外汇总不是只做一次。ReviewerAgent 如果发现初稿里“结论缺少数据支撑”会把缺陷反馈给 Supervisor。Supervisor 这时要做第二轮调度把缺陷描述附在任务里重新分派给对应的专家 Agent 修改。这个“检查-反馈-再调度”循环是整个 Supervisor 模式最能体现价值的地方。你可以把 ReviewerAgent 当成团队里的测试岗位它不直接写报告但它的反馈决定了报告能不能发出去。5. 调试与稳定性我在实战中踩过的坑多 Agent 系统最大的问题不是“跑不起来”而是“跑起来之后怎么稳定不出错”。这一章我挑几个真实的坑摊开讲希望你不用再走一遍。5.1 Agent 之间的“脏数据”污染一次典型事故复盘我第一次把这套系统上线时遇到过一个问题WriterAgent 生成的报告里某个数据比 DataAgent 给出的原始指标多了整整 10 倍。查了半天发现是 DataAgent 在返回结果时顺手把一段错误的状态日志也塞进了 result.content 字段。下游 WriterAgent 读到了这段日志把它当成了真实数据最后逐字写进了报告。这就是典型的脏数据污染。根因很简单专家 Agent 的输出没有做严格的 schema 校验带格式的日志混进了业务数据。修复办法也很粗暴在 DataAgent 和 WriterAgent 之间加一个校验器result.content 只允许包含 JSON 格式的指标对象其他一律丢弃。从那以后我再也不相信任何 Agent 会“自觉”遵守输出格式而是要写一层代码做强制约束。经验总结在多 Agent 系统里接口规范和你企业内部微服务之间的契约一样重要。每个 Agent 的输入输出都要有类型定义、有校验逻辑而不是让下游 Agent 用大模型能力去“猜”。5.2 死循环、重复调用与超时治理另一个高频问题是死循环。Supervisor 把任务派给 DataAgentDataAgent 返回了一个格式错误的结果Supervisor 要求重做DataAgent 又返回格式错误如此反复。如果没有重试限制这个循环会一直跑到预算耗尽。我在这里用了三招。第一招是在 Supervisor 上设置 max_retries2达到上限后直接标记任务失败不再继续尝试。第二招是给每个子任务设置超时时间超过 30 秒没返回就直接判定失败避免个别 Agent 因为模型调用阻塞而拖垮整体流程。第三招是设置金融预算钟每次调用之前检查当前 token 消耗超过预算就降级处理比如把任务回退给单一 Agent 用简单模式完成。这三招放在一起整个系统才算有了“熔断”能力。一个稳定的多 Agent 系统不是保证每一步都不出错而是保证出错之后能快速停止、快速恢复不让个别异常拖垮全局。5.3 如何验证专家 Agent 真的“专业”最后一个坑最隐蔽如何确定你的专家 Agent 真的有专家水平而不是表面意义上做得“像模像样”。如果只是拿一两个例子人工看一遍很可能得出“效果不错”的结论一旦放开真实流量各种幻觉就冒出来了。我的做法是建立一个小型回归测试集。找 20 到 50 个历史真实请求把预期结果写成结构化标签比如“结论是否引用了 DataAgent 返回的指标”“报告里是否存在虚构数据”“图表路径是否真实存在”。每次修改模型、提示词或工具定义之后跑一遍测试集统计通过率。还有一项更轻量的冒烟测试故意给某个专家 Agent 一个不完整的数据集看它是否会“编造”出缺失的数据。很多 Agent 在数据不足时为了显得专业会无中生有捏造一个数字这种问题只有通过针对性测试才能暴露。我把这个测试写成了固定用例每次上线前必跑发现一次就调整一次提示词。6. 进阶优化思路从能跑到跑好当你的 Supervisor 团队能稳定跑通一天之后就可以开始琢磨优化了。优化不是说模型换得更强而是让系统在成本、响应速度、可扩展性上都能适应生产要求。6.1 记忆与状态管理全局状态跟着 Supervisor 走多 Agent 系统里的“记忆”很容易被过度设计。一开始我试图让每个 Agent 都有自己的长期记忆模块结果发现维护成本极高每个 Agent 记了一堆和当前任务无关的历史反而干扰判断。后来我定了一个原则全局状态只归 Supervisor 持有专家 Agent 只有任务级临时记忆。Supervisor 用一个轻量的向量库存“用户偏好”“项目背景”“历史决策原因”每次派发任务时把相关记忆摘录出来放进子任务上下文。专家 Agent 的上下文只在单个任务周期内有效任务结束就丢。这样既保留了“团队记得住以前聊过什么”的能力又不会让每个专家的上下文无限膨胀。6.2 成本控制上下文裁剪与模型分级多 Agent 模式和单 Agent 相比token 消耗天然会更高因为同样一个信息可能要转发好几轮。直接的办法是上下文裁剪。比如派发给 DataAgent 的任务只带上相关字段名和数据筛选条件不把整份 Excel 描述全塞进去派发给 WriterAgent 的任务只带结构化指标不附带原始查询日志。更进一步的玩法是模型分级。Supervisor 的调度和意图识别用便宜的轻量模型比如 qwen-turbo 级别专家 Agent 负责产出内容和执行代码时再上更强模型比如 qwen-max 级别。这样能省不少钱而且质量不会明显下降因为拆解任务这件事本身不需要太强的推理能力真正烧脑的是专家干活。我还在 Supervisor 层的提示词里强制要求“不要重复传输已经在上一轮出现过的数据”只传关键摘要和路径。一开始模型经常忽略但配合输出校验器强制过滤后整体 token 消耗下降了约 40%。6.3 从 Demo 到生产灰度发布与可观测性最后想聊的是把 Supervisor 模式推到生产环境时容易漏掉的一环可观测性。多 Agent 系统比单 Agent 系统难定位问题得多因为一次用户请求可能会触发十几个模型调用和几十次工具执行任何一个环节都可能出问题。我会在每次请求开始时生成一个 trace_id贯穿整个调度链路然后把 Supervisor 的每次决策、专家 Agent 的每次输入输出、每个工具的执行时间都记录到日志系统。用不用 AgentScope 自带的可视化组件都可以核心是日志结构要统一、带 trace_id、有耗时和 token 数。有了这些基础才能做灰度发布先让 5% 的流量走新架构对比关键指标确认无误后再逐步放大。我的建议是先小范围试点。不要一上来就给 Supervisor 配八个专家 Agent先用“一个 Supervisor 两个专家 Agent”跑一个小业务把日志、监控、重试机制全部跑顺再慢慢扩角色。没有可观测性之前多 Agent 系统就是个黑盒出了问题只能抓瞎把这层地基打牢后面加多少 Agent 都不慌。