“agency-agents”这个名字，第一眼看上去像是把一个“代理机构”变成了一群智能体的集合。我最早对这个项目产生兴趣，是在尝试把内容生产的效率再往上提一档的时候。单条流水线接一个模型调用已经不够用了，真正能把事情跑起来的，是一组各司其职的智能体，有人负责拆解任务，有人负责执行，有人盯质量，还需要一个人来统筹全局。agency-agents 解决的就是这个“多人协作”的问题：它不是做一个更聪明的 Agent，而是做一套让多个 Agent 能高效配合的机制。
这套思路适合两类人。一类是已经在用 AI 做自动化，但发现单个模型总是“顾头不顾尾”工程师；另一类是团队管理者，想在项目里引入 AI 员工，但不知道从哪儿下手。接下来的内容我会从头拆一遍项目的设计逻辑、落地时踩过的坑，以及一套可以直接参考的搭建方案。
1. 项目定位：为什么需要一个智能体“代理机构”
1.1 单智能体的天花板
不管底层接的是哪种大语言模型，单个智能体的能力边界都很明显：它能写一小段代码，但做不到从需求到提交的完整闭环；它能根据提示词生成一篇初稿，但不会自己去校验事实、优化排版、补全缺失信息。你当然可以把所有要求都塞进一个提示词里，让它做“全能选手”，但实测下来，提示词越长，模型越容易在中间丢失指令，输出质量反而跳水。
问题的本质在于，单智能体是一条线性执行链：输入一个任务，模型从头推理到尾。中间任何一个环节出错，整个输出都要推翻重来。而且没有分工就没有责任边界，模型不会告诉你“这一步超出我的能力范围”，它只会硬着头皮继续写，结果就是一本正经地编造内容。
1.2 从单个 Agent 到 Agent 团队
多智能体系统最核心的变化，是把一个庞大任务拆成若干个子任务，每个子任务由一个专职的 Agent 负责。这些 Agent 之间有明确的输入输出接口，像一个工厂里的不同工位：原料进来，加工，流向下一道工序。这一步做好之后，系统的容错能力和可控性都会明显提升。
我在项目里把整个流程设计成“五个人”的团队：规划者负责拆解任务，研究员负责收集信息，写作者负责产出初稿，审查者负责挑毛病，最后的统筹者负责把各部分拼装成完整结果。
这种设计带来的额外好处是，你可以单独替换任何一个角色。比如某个 Agent 的提示词效果不好，或者某个环节需要人工介入，只调整这一环就行，不用动整个系统。
1.3 适用场景与受众
从实际落地来看，最适合这套模式的任务有三个特征：流程可拆解、各环节有相对独立的标准、最终产出需要一定的多角度质量保证。最典型的是内容生产流程：选题、搜集资料、撰写、校对、排版，每一步都能独立验收；其次是数据分析报告的生成，数据清洗、探索性分析、结论推断、可视化建议，每一段都可以安排专职 Agent；软件开发场景也适用，需求分析、代码生成、单元测试、代码审查，层级清晰。
如果你只是想让一个对话机器人回答问题，那多智能体方案暂时不用考虑，单模型加 RAG 就足够了。但如果你做的系统需要在一小时甚至几分钟内交付一个完整成果，那 agency-agents 这套思路就值得认真参考。
2. 整体架构与核心设计思路
2.1 先定岗位，再定职责
搭建多智能体系统，不能上来就写代码，第一步是画出岗位分工图。这个图不用很复杂，但要回答两个问题：这个系统最终要交付什么？完成这个交付需要哪些不可替代的能力？
以我搭建的内容生产系统为例，最终交付是一篇结构完整、信息准确的科普文章。拆解下来需要的能力包括：理解需求文档、搜索和筛选信息、组织语言、核查逻辑漏洞、统一文风。对应到 Agent 岗位，就产生了规划者、研究员、写作者、审查者四个角色。其中审查者不参与写作，只负责挑错，这样才能保证质量把关的独立性。
岗位定义阶段最容易犯的错误是角色过多过细。我一开始设计了七个 Agent，光是“标题生成”和“摘要生成”就分成了两个角色，结果它们之间的依赖关系变得非常复杂，经常因为其中一个角色返回格式不对，整条流水线卡住。后来合并同类项，把系统精简到五个角色以内，稳定性提升了一个档次。
2.2 Agent 之间怎么“说话”
多智能体系统最容易翻车的地方，是 Agent 之间的通信格式。如果让一个 Agent 的输出直接变成另一个 Agent 提示词里的自然语言段落，系统会非常脆弱：模型换个说法，后面的 Agent 就理解偏了。我在项目中统一使用 JSON 作为通信协议，每个 Agent 的输出结构在工程层面做校验，不符合格式就进入重试流程。
通信字段也要精简。每个 Agent 只关心自己需要的字段，不要把所有中间过程全部传给下游。以“写作者”为例，它只需要接收“选题方向”“素材列表”“字数要求”三样东西，不需要看到规划者内部的全部思考过程。字段一多，模型注意力就会被无关信息稀释，输出质量下降。
2.3 编排模式：中央调度还是自由协作
多智能体有两种主流编排方式：集中式编排和去中心化协商。agency-agents 项目采用的是集中式：一个 orchestrator 负责创建任务、分配任务、收集结果、处理错误。这样做的好处是状态可控，所有上下文都在一个地方维护，排错时只需要看调度日志。
去中心化模式我也试过，每个 Agent 直接发消息给其他 Agent，像一群人拉微信群聊工作。这种模式在实验环境看着很灵活，但一旦进入生产环境就是灾难：没有统一的状态管理，Agent 之间的消息丢失了你根本不知道是哪一环的问题，而且模型输出的不确定性会被放大。如果你的系统还处于探索阶段，我建议直接选集中式编排，等跑通之后再考虑演进。
3. 技术选型与开发环境搭建
3.1 编程语言与多智能体框架
语言层面我选了 Python，没有特别复杂的原因，就是生态最全。大模型 SDK、数据处理库、任务队列组件都优先兼容 Python，团队接手成本也最低。异步框架用了 asyncio，因为多智能体之间的调用大多数是 I/O 密集型；同步写法在并发量上来之后会明显拖速度。
Framework 层面，我建议不一定非要引入重型的 Agent 框架。如果只是编排三五个 Agent，纯手写一个状态机加任务队列，反而更灵活，也更可控。我在早期用过一些开源的多智能体框架，确实开箱即用，但出了 bug 之后你很难判断是框架的问题还是自己代码的问题。后来我自己写了一个轻量调度模块，核心不到 300 行，但每一条执行路径都清清楚楚。当然，如果团队规模大、需要快速验证，用成熟框架没有问题，注意预留自定义扩展点就行。
3.2 模型服务接入的取舍
模型接入是整个系统里变量最大的部分。我在设计 agency-agents 时做了一个抽象层，所有 Agent 都通过同一个接口调用模型，底层可以是不同的模型版本，甚至可以是不同厂家的服务。抽象层的好处是可以针对不同角色选模型：规划者需要一个上下文理解能力强、指令遵循度高的模型；写作者需要文风稳定、生成速度快的模型；审查者则需要逻辑严谨、判断力强的模型。
一个很实际的建议是，不要让所有 Agent 都使用同一个模型，成本会失控，而且单一模型的偏好会被放大。比如同一个模型既当写作者又当审查者，它往往看不出自己生成的文本里的逻辑问题，因为思维惯性是相同的。
3.3 工程设施：日志、存储与可观测性
多智能体系统的排错难度高于普通应用，因为每个 Agent 的输入输出都包含大量自然语言，出了问题很难直接用单行日志定位。所以我从项目一开始就强制要求三个基础设施：
第一，完整的执行日志。每一条任务都要记录：任务 ID、发起者、接收者、输入摘要、输出摘要、耗时、token 消耗。第二，结果持久化。每个 Agent 的原始输出都存储到数据库里，不只是存最终结果，中间结果也要留，因为下游 Agent 可能产出错误，你需要回溯是哪一份中间结果导致的。第三，执行可视化。不一定要用复杂工具，一个简单的 Web 界面能看当前任务卡在哪个环节就够了。
这三个设施看起来平平无奇，但真正发生线上故障时，它们会决定你是花 10 分钟定位问题，还是花一整天重跑流程。
4. 实操过程：从零搭建一个最小可用的 Agent 团队
4.1 第一步：定义角色文件
我习惯把每个 Agent 的角色定义放在一个独立的配置文件里，而不是直接写死在代码里。角色文件包含四个部分：角色名称、角色目标、输入输出结构、行为约束。以“研究员”为例，它的角色目标是“根据规划者给出的问题清单，查找可靠信息并返回带出处的材料”；输入结构是“问题列表、搜索关键词列表”，输出结构是“素材列表，每项包含内容、来源链接、可信度评分”。
角色配置文件写好之后，等于把整个系统的“人力资源制度”定下来了。后续调效果时，只要改配置、重跑，不用改代码逻辑。我公司里一位测试同学接手这个项目时，只花了半小时就通过角色配置文件理清了整套系统的职责边界。
4.2 第二步：实现任务分发与结果回收
任务分发模块是系统的骨架。我用一个 Python 类实现了一个极简调度器：维护一个待执行队列和一个结果汇总表，调度器从队列中取出任务，调用对应 Agent 的执行函数，拿到结果后存入汇总表，再根据依赖关系决定下一个可以执行的任务。
关键点在于异常分支的处理。每个 Agent 的执行函数都要包一层重试逻辑，模型返回格式不合法时自动重试一次，重试仍然失败就走“降级路径”：比如把该任务标记为失败，同时通知统筹者跳过这个环节继续后面的流程，而不是让整个 pipeline 卡死。
这里有一个设计取舍：有时候强依赖关系不能跳步，比如“写作者”必须依赖“研究员”的素材才能动笔，但如果研究员失败三次，系统仍然会等待，造成了不可接受的延迟。后来我加了一个超时上限，超过 60 秒未拿到结果，就使用缓存的历史素材顶上，宁可素材旧一点，也不能让整个系统挂起。
4.3 第三步：加入人机复核环节
纯无人干预的多智能体系统在初期上线时并不现实。我最终跑通的一套最小闭环里，安排了一个人类“编辑”角色，只在两个节点介入：规划者输出任务拆解之后，和审查者输出质量报告之后。这两个节点是全局正确性的关键，机器判断容易出错，但人类的短期介入能大幅降低错误率。
不过人机复核不能做成全流程的“人工审批”，否则就失去了自动化意义。我的做法是只在高风险环节加人工确认，比如内容系统里涉及事实性观点的输出，必须经过人工批准才能继续。其他低风险步骤，比如格式转换、初步检索，自动执行即可。
5. 核心环节深度剖析
5.1 上下文传递：从“大锅烩”到“定食”
多智能体系统的上下文管理是最容易翻车的地方。很多人的第一反应是“让每个 Agent 都能看到所有历史消息”，这种做法看起来信息全，实际上副作用很大。模型对长上下文的注意力并不均匀，越是早期的信息越容易被忽略。多个 Agent 的中间输出混合在同一段上下文里时，指令、事实、噪声边界会变得模糊。
我采用的方式是“定食式传递”：每个 Agent 只能看到完成自己任务所需的最小上下文集。比如规划者给研究员下达任务时，只传递问题清单和相关背景，不传递其他 Agent 的执行记录；写作者拿到的素材已经经过结构化清洗，不会看到研究员检索时用的原始网页噪音。
这么做还带了一个好处：token 消耗显著下降。在同样完成一篇长文生成任务的前提下，我的 token 成本大约是“全部上下文共享”方案的 40%。在追求效率的项目里，这个差距非常可观。
5.2 失败重试与任务回滚
多智能体系统是全链路概率系统，任何一个 Agent 的输出都有一定概率偏离预期，所以失败处理机制必须设计在系统的“骨架”里，而不是事后补救。我在项目里为每个 Agent 设置了最多三次重试、每次重试之间指数退避间隔的重试策略。
除了重试，任务回滚也很重要。假设写作者生成的文本被审查者判定为不合格，需要重新生成，但写作者重新生成时需要基于同一份素材，而不是基于它自己上次的输出，否则会产生自激振荡——越改越错。因此调度器在重试任务时，始终回退到该任务对应的初始输入，这相当于给 Agent 一次“从头再来”的机会。
如果重试多次仍然失败，就不必继续耗资源了。我的策略是给系统一个全局“熔断开关”：某个环节连续失败超过五次，系统自动转换到半自动模式，所有任务转给人处理。人工介入一次之后，把修复后的结果重新注入流程，作为后续任务的参考样本，这样系统也能从自己的失败中学习。
5.3 成本与速度的平衡
多智能体系统的成本比单模型调用高很多，因为一次完整任务需要多次模型调用。我在成本控制上做了三件事。第一是“模型分级”，简单任务用廉价快速的小模型，复杂判断才用大模型；第二是“缓存优先”，同一角色的输入如果经过哈希比对是重复的，直接复用历史输出，不做模型调用；第三是“延迟计算”，让部分 Agent 采用流式输出，结果先从调度器层汇总，后续真正到最终收尾环节才调用完整模型做合并。
速度方面，除了并行化，我还把部分 Agent 从“同步调用”改成“异步回调”。例如研究员任务列表里有多个子问题，我可以把每个子问题分别发给同一个 Agent 的不同实例，等所有子问题返回后统一汇总。只要 Agent 之间没有数据依赖，并行度拉满，整体耗时能从串行的十几分钟缩短到两分钟以内。
6. 常见问题与排查实录
6.1 回复格式不稳定
多智能体系统最常见的故障，就是某个 Agent 突然不按约定的 JSON 格式返回内容。代码里动不动就报JSONDecodeError。原因通常是提示词里强调了格式，但模型还是不听，尤其是上下文里夹带了太多别的 Agent 输出时。
我最终采取了三层防线：第一层，提示词自带一个 JSON Schema 示例，并在系统消息里固定；第二层，代码解析失败时用正则切出最外层的大括号再试一次，能挽救一部分输出；第三层，两次解析都不成功就走重试逻辑，不把希望全押在模型的一次生成上。这套防线把格式解析导致的失败率从 12% 降到了 0.5% 以下。
6.2 Agent 之间出现循环调用
在集中式编排下，循环调用的问题相对少见，但如果调度逻辑没写好，还是会出问题。我踩过的案例是：审查者发现自己被写作者错误修改，触发了“重新规划”，而重新规划模块又调用了写作者，写作者又返回给审查者，形成循环。
排查方法很简单，所有执行节点维护一个调用链深度计数，超过设定阈值直接中断并报警。在报警信息里附带完整调用链，一眼就能看出循环发生在哪一步。
6.3 上下文污染与记忆混乱
多智能体系统虽然有独立的上下文传递机制，但下游 Agent 还是会拿到一些“不该看”的内容。例如研究员返回素材时附带了它对素材的初步判断，这些判断传给了写作者，写作者就把它当成最终事实，结果文章里出现了未经核实的观点。
这个问题只能靠严格的数据结构解决。我在每个 Agent 的输出 schema 里加了一个internal_notes字段，明确标记“仅供本角色使用，不可传递给下游”。调度器在传递数据时把这个字段剥离掉。这就是一个非常简单的“数据脱敏”动作，但能避免大量的上下文污染问题。
6.4 Agent 执行顺序与依赖关系的隐性错误
Agent 之间的依赖关系如果只靠人脑记忆，很容易在系统升级时搞乱。比如我给系统新增了“事实校验 Agent”后，忘记了写作者生成内容之前其实不需要校验结果，校验只需要在审查阶段触发，结果系统多跑了好几次无效调用。
后来我引入了依赖关系声明表，每个任务在执行前先通过拓扑校验，确认它依赖的上游任务全部完成，且没有上游任务被跳过，这才解决。这张表一遍跑起来之后，整个系统像一条固定的流水线，每个环节都在正确的时间点被触发。
| 故障类型（我可提供故障） | 核心原因 | 解决思路 |
|---|---|---|
| JSON 格式不稳定 | 模型输出与约定结构不一致 | 三层防线解析 + 失败重试 |
| 循环调用 | 调度逻辑依赖配置错误 | 调用链深度计数 + 熔断报警 |
| 上下文污染 | 内部字段被下游误读 | 输出 schema 增加剥离字段 |
| 依赖关系错乱 | 新 Agent 接入未更新调度配置 | 依赖关系声明表 + 拓扑校验 |
7. 优化经验与扩展方向
7.1 让 Agent 学会互相审校
多智能体系统比单模型强的绝不仅仅是“分工”，更是“制衡”。我在生产环境里体会到的最有价值的设计，是引入一个专门的“对抗角色”：它存在的目的不是帮其他 Agent 完成任务，而是想办法证明对方的结果有问题。
这个角色就是审查者。它不是格式校对工具，而是质疑者。它逐条审视写作者的论点是否有事实支撑，规划者的任务拆解是否有遗漏，研究员的素材来源是否可靠。审查者的提示词里明确加了一句话：“不要对结果说好话，你要输出所有可能出错的点，并给出验证方式。”这大大提升了系统最终交付物的质量，胜过我在提示词里反复要求“请务必保证准确性”的效果。
7.2 多实例并行与水平扩展
有一段时期任务量暴增，单个调度器进程明显不够用。我把 Agent 执行函数全部改造成无状态的，也就是每个 Agent 的执行只依赖当前任务数据，不依赖内存中的公共状态。改造完成之后，我直接在消息队列后面开了九个相同的执行容器，调度器分发任务时按队列长度做负载均衡，整体吞吐提升了接近八倍。
这里有一个教训：无状态化不是可选项，而是扩展的前提。如果某个 Agent 的代码里引用了全局变量或者读了本地临时文件，那么一旦部署多个实例，状态就会互相覆盖。我在第一次做多实例部署时，就因为在写作者代码里用了一个本地缓存文件，结果两个实例同时写入，导致素材数据损坏。
7.3 从任务级编排到流程级编排
agency-agents 最初只处理单个任务的批量执行，但现实中的业务往往是一条流程：需求进来，自动生成方案，方案通过评审后自动进入生产，生产产出后自动归档。把这些跨任务的编排逻辑也纳入智能体系统，就进入流程级编排。
流程级编排的核心是引入一个“流程状态机”，每一步不仅指向一个 Agent 任务，还定义了状态转移条件。我在扩展时借鉴了工作流引擎的思路，用 YAML 定义流程节点、条件分支、回退规则。每个节点绑定一个 Agent 角色，整个流程就是一个有向图。这样做的好处是，业务方调整流程时不需要改代码，只要改 YAML 配置即可。
我个人在实际操作中的一个体会是：多智能体系统的难点不在于让单个 Agent 表现更好，而在于处理好它们之间的“组织关系”。组织关系理顺了，系统稳定性、扩展性和可维护性都会有质的提升。
最后分享一个关于调优的小技巧：当你发现某个 Agent 输出质量下降时，不要急着改提示词，先看一下它收到的是不是最近几次迭代中被污染过的数据。很多时候模型本身没问题，问题是上游给它喂了不干净的东西。把上游数据修好，才是一个系统工程师该做的事。这个项目后续我还会继续在流程自动化、多团队协同和更细粒度的模型路由上做尝试，如果你也在做类似方向，欢迎一起交流。
