企业官网建设流程全解析

最近我把一个内部数据报告系统从单一 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 做完给 B，B 做完给 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( name="DataAgent", role="数据查询与清洗专家", system_prompt=( "你负责查询数据库、清洗数据、计算关键指标。" "输出必须是结构化 JSON，包含指标名和数值。" ), tools=[ Tool("query_database", params={"sql": "str"}), Tool("clean_dataframe", params={"rule": "str"}), ], model="qwen-max", ) # 代码执行专家 code_agent = Agent( name="CodeAgent", role="Python 代码执行与图表生成专家", system_prompt=( "你负责编写并执行 Python 代码，生成图表。" "只能输出代码执行结果和图表保存路径。" ), tools=[ Tool("python_executor", params={"code": "str", "timeout": 30}), ], model="qwen-max", ) # 报告撰写专家 writer_agent = Agent( name="WriterAgent", role="数据报告撰写专家", system_prompt=( "你负责把结构化数据转换成逻辑清晰的中文报告。" "不得创造数据，所有数字必须来自输入。" ), tools=[ Tool("markdown_render", params={"content": "str"}), ], model="qwen-max", )

这套配置的关键点不在字段名，而在于两个设计细节。第一个是给 Agent 的 system_prompt 里写清楚“你只能做什么、绝不能做什么”，比如 WriterAgent 被明确禁止创造数据，这就减少了数据幻觉。第二个是每个 Agent 的工具数量被压缩到了 1~2 个，模型做工具选择的压力会小很多。

3.3 Supervisor 的提示词与任务分发逻辑

Supervisor 的配置比普通 Agent 多了一层“成员列表”和“分发策略”。核心提示词我写了大概两百字，重点不是文采，而是把流程说死，让模型知道什么时候该做什么。

supervisor = SupervisorAgent( name="Supervisor", members=[data_agent, code_agent, writer_agent], system_prompt=( "你是一个多智能体团队的主管。团队成员包括：" "DataAgent（数据查询与清洗）、CodeAgent（代码执行与图表）、" "WriterAgent（报告撰写）。" "当收到用户目标时，你必须：" "1. 拆解为子任务，每个子任务必须匹配一个或多个成员；" "2. 将子任务按依赖关系排序；" "3. 等待成员返回结果，并对结果做质量判断；" "4. 如果结果不合格，向成员反馈原因并要求重做，最多重试两次；" "5. 汇总所有结果，生成最终回答，确保引用真实返回的数据。" "不要替成员完成他们的工作。" ), task_strategy="dependency_graph", # 按依赖关系分发 max_retries=2, )

任务分发逻辑上，我用的是“先拆成依赖图，再按拓扑序下发”。比如“画图表”必须等“算指标”完成，“写报告”必须等“画图表”完成，这些依赖关系写死在任务定义里。如果两个子任务没有依赖关系，我会把它们并行下发给不同 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 约束它，把子任务清单写成一个标准结构。我期望的拆解结果大致是这个样子：

这个表格看起来很直白，但真正考验 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 或者 partial，Supervisor 会读取 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 把任务派给 DataAgent，DataAgent 返回了一个格式错误的结果，Supervisor 要求重做，DataAgent 又返回格式错误，如此反复。如果没有重试限制，这个循环会一直跑到预算耗尽。

我在这里用了三招。第一招是在 Supervisor 上设置 max_retries=2，达到上限后直接标记任务失败，不再继续尝试。第二招是给每个子任务设置超时时间，超过 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 都不慌。