1. 从一个人扛所有到一群Agent各管一摊这套协作系统到底在解决什么如果你带过三人以上的开发小组大概率经历过这种场面需求评审时人人点头排期表拉出来漂漂亮亮真到联调阶段却发现接口对不上、字段命名各写各的、前端等后端、后端等数据、测试等所有人。问题不在于谁不努力而在于协作本身没有被当成一个工程问题来对待。Agency Agents 这套多智能体协作系统本质上就是把团队协作这件事从口头约定变成可编排、可观测、可回滚的工程结构。它不是一个具体的业务框架而是一层协作调度层——你可以把它理解成给一群各有所长的 AI Agent 配了一个项目经理、一套工单系统和一本共享的接口手册。它适合谁三类人最该关注一是正在做 AI 应用落地、被单 Agent 能力天花板卡住的开发者二是想用多智能体思路重构内部工具链的技术负责人三是对 Agent 编排感兴趣、但被各种概念绕晕、想找一个能跑起来的参照系的人。这篇文章不讲空泛的智能体时代来了只拆架构、讲取舍、给能抄的配置。先说清楚一个前提多智能体不是Agent 越多越强。我见过太多项目一上来就堆七八个角色结果调度开销比任务本身还大最后退化成一个 Agent 干活、六个 Agent 围观。Agency Agents 的设计哲学恰恰相反——先定义协作边界再决定要不要拆角色。这个顺序搞反了后面全是坑。2. Agency Agents 的骨架角色、消息总线与共享状态三件套2.1 角色定义不是写人设是划职责边界很多人第一次接触多智能体第一反应是给每个 Agent 写一段你是一位资深后端工程师的人设提示词。这在 Agency Agents 里只是最表层的东西。真正决定系统能不能跑通的是每个角色的输入契约和输出契约。我拿一个典型的开发场景举例一个需求拆解 Agent、一个接口设计 Agent、一个实现 Agent、一个校验 Agent。这四个角色的关键不在于提示词写得多花哨而在于需求拆解 Agent 的输出必须是结构化的任务列表每条任务带明确的验收标准字段接口设计 Agent 只接受任务列表作为输入输出是接口定义字段名、类型、必填性实现 Agent 只认接口定义不允许自己发明字段校验 Agent 拿接口定义和实现产物做比对输出差异报告。看出来了吗角色之间的耦合点全部落在数据结构上而不是自然语言上。这是整套系统能稳定的根本原因。自然语言在 Agent 之间传递时信息损耗极大同一个用户ID能被写成 userId、user_id、uid、用户标识四种形态联调时就是灾难。提示定义角色时先画一张表列出每个角色的输入字段和输出字段字段对不上的地方就是未来必炸的地方。这张表比任何提示词工程都重要。2.2 消息总线为什么不用简单的函数调用串起来初学者最容易想到的实现是Agent A 跑完把结果直接传给 Agent B 的函数。简单直接但一旦角色超过三个、出现分支和重试代码就会变成一团意大利面。Agency Agents 采用的是消息总线 订阅的模式。每个 Agent 不直接调用下一个 Agent而是把结果作为一条消息投递到总线上带上类型标签比如task_list、interface_spec、impl_artifact。需要这类消息的 Agent 订阅对应标签。这样做换来三个实打实的好处第一解耦。新增一个文档生成 Agent只需要订阅interface_spec完全不用改动接口设计 Agent 的代码。第二可观测。所有消息都在总线上留痕出问题时你能完整回放谁在什么时候产出了什么而不是靠日志里零散的 print 去猜。第三可重试。某条消息处理失败重新投递即可不需要从头跑整条链路。代价也很明显调试时链路变长一个 bug 可能藏在消息序列化的某个角落。我的经验是在开发阶段一定要给总线加一个消息快照开关把每条消息的原始内容落盘排查效率能提升一个数量级。2.3 共享状态哪些东西该共享哪些坚决不能共享共享状态是双刃剑。共享得好所有 Agent 看到同一份事实共享得烂就是并发写冲突和状态污染。Agency Agents 的实践原则是只共享事实不共享过程。具体来说接口定义、任务清单、最终产物这些是事实放进共享状态而某个 Agent 的中间推理、草稿、临时变量坚决留在 Agent 内部不往共享区写。我踩过的一个坑早期把当前进度百分比也放进共享状态结果多个 Agent 同时更新数值来回跳前端展示像抽风。后来改成每个 Agent 只上报自己的状态由调度器统一汇总问题立刻消失。共享状态应该是只读为主、写入受控的谁都能随便写的共享区迟早出事。3. 调度策略串行、并行还是动态编排选错了全盘皆输3.1 三种调度模式的适用边界调度策略决定了 Agent 之间的执行顺序选错了要么慢得离谱要么错得离谱。Agency Agents 支持三种基本模式我把它们的适用场景整理成表调度模式执行方式适用场景主要风险串行流水线A→B→C 依次执行强依赖链路如需求→设计→实现单点阻塞一个环节慢全链路慢并行扇出A 同时触发 B、C、D独立子任务如多模块同时实现结果汇总时的冲突合并动态编排由调度器按状态决定下一步复杂分支、需要重试和回退调度逻辑本身容易变复杂大部分团队的真实项目是混合模式需求拆解到接口设计是串行强依赖多个模块的实现是并行互相独立校验和修复是动态编排失败要回退重做。3.2 动态编排的判定逻辑怎么写才不失控动态编排最诱人的地方是智能最危险的地方也是智能。如果让一个 LLM 自由决定下一步调谁系统会变得不可预测。Agency Agents 的做法是把决策规则显式化LLM 只负责在规则框架内做有限选择。举个具体的判定逻辑校验 Agent 输出差异报告后调度器按以下规则走——差异为空任务完成进入汇总差异仅涉及字段命名触发轻量修复只重跑实现 Agent 的格式化步骤差异涉及接口结构回退到接口设计 Agent 重新产出连续两次修复失败升级为人工介入标记停止自动重试。这套规则是写死的不是让模型自由发挥的。规则负责能不能做模型负责怎么做这个分工是多智能体系统稳定的关键。我见过让模型全权决定调度顺序的项目跑十次有三次进入死循环最后不得不加一个最大步数硬性熔断。3.3 熔断与超时没有这两样系统迟早挂死任何多智能体系统都必须有熔断机制。Agency Agents 里我建议至少配三层保护第一层是单 Agent 超时比如单个 Agent 处理超过 60 秒强制中断避免某个环节卡死拖垮全局。第二层是链路总步数上限比如整条任务链最多 20 步超过就判定异常。第三层是重试次数上限同一个环节最多重试 2 次第三次直接标记失败并保留现场。这三层看起来简单但缺任何一层都会在真实项目里翻车。我印象最深的一次是某个 Agent 因为输入格式异常陷入重试-失败-再重试的循环一晚上烧掉了大量调用额度第二天看账单才发现。熔断不是可选项是必选项。4. 落地实操从零搭一个能跑的最小协作系统4.1 环境与依赖准备中最容易被忽略的两件事搭这套系统技术栈其实不挑Python 或 Node 都能做。但有两件事新手几乎必踩第一消息序列化格式要统一。Agent 之间传的如果是 JSON就全程 JSON别一会儿 JSON 一会儿 YAML 一会儿纯文本。格式不统一解析代码会写到你怀疑人生。我建议用 JSON Schema 把每种消息类型的结构固定下来投递前先校验。第二给每个 Agent 配独立的超时和重试配置不要全局一刀切。接口设计 Agent 可能要想很久实现 Agent 相对快用同一个超时值要么误杀要么白等。# 消息结构定义示例基于常见实践的补充 AGENT_CONFIG { requirement_splitter: {timeout: 90, retry: 1, output_type: task_list}, interface_designer: {timeout: 120, retry: 2, output_type: interface_spec}, implementer: {timeout: 60, retry: 2, output_type: impl_artifact}, validator: {timeout: 45, retry: 1, output_type: diff_report}, }4.2 核心链路跑通的最小步骤不要一上来就追求完整功能先把需求→设计→实现→校验这条最短链路跑通。具体步骤定义四种消息类型的数据结构写死字段实现一个最简单的内存消息总线支持投递和订阅每个 Agent 先写成假实现——输入固定、输出固定验证链路能通逐个把假实现替换成真实的模型调用加上超时、重试、熔断最后接共享状态和可观测日志。这个顺序的核心逻辑是先保证结构对再保证内容对。很多人反过来先调模型效果结果链路结构一塌糊涂模型再好也白搭。第 3 步的假实现特别重要它让你在没有任何模型成本的情况下验证整个骨架。4.3 跑通 Demo 之后立刻会遇到的三个坑Demo 跑通那一刻很爽但接下来三个坑几乎躲不掉坑一消息顺序错乱。并行扇出时多个 Agent 的结果到达顺序不确定如果你的汇总逻辑假设了固定顺序就会偶发错误。解决办法是给每条消息带时间戳和序号汇总时显式排序。坑二上下文膨胀。每个 Agent 都往共享状态里塞东西跑几十轮之后上下文大到模型处理不动。解决办法是给共享状态设生命周期任务完成后清理中间产物只保留最终结果。坑三错误传播。上游 Agent 产出了一个格式正确但语义错误的结果下游全盘接受最后错误被放大。解决办法是在关键节点加语义校验比如接口设计出来后用一个独立的校验 Agent 检查字段是否覆盖了需求里的所有实体。5. 协作质量的真正瓶颈不在模型在接口契约5.1 为什么字段命名这种小事能拖垮整个系统我在多个项目里反复验证过一个结论多智能体系统的失败八成不是模型能力不够而是接口契约没定清楚。字段命名、类型、必填性、默认值、边界条件——这些在人类团队里靠沟通解决的东西在 Agent 之间必须靠契约解决。举个真实感很强的例子需求里写用户可以有多个标签接口设计 Agent 理解成tags: string[]实现 Agent 理解成tags: string逗号分隔校验 Agent 按数组校验三方各说各话。这种问题在人类团队里一个 Slack 消息就解决了在 Agent 之间如果没有契约会一直错到联调。所以 Agency Agents 里我强烈建议接口定义一旦产出就冻结成契约文件所有下游 Agent 只读不改。要改可以走契约变更流程重新触发受影响的下游。5.2 契约的版本管理别让改一个字段引发雪崩契约冻结之后必然会有变更需求。如果没有版本管理改一个字段名可能导致所有下游 Agent 的产物全部失效。我的做法是给契约打版本号Agent 订阅时声明自己依赖哪个版本。契约升级时新旧版本并存一段时间下游 Agent 逐步迁移。这听起来像微服务的接口版本管理没错多智能体协作本质上就是一套微服务架构只不过服务是 Agent。把微服务那套契约治理经验搬过来能少走很多弯路。5.3 校验 Agent 该怎么设计才不是摆设很多项目的校验 Agent 形同虚设因为它只做格式对不对的检查不做语义对不对的检查。真正有用的校验要分三层格式层字段类型、必填性、枚举值是否合法语义层接口是否覆盖了需求里的所有实体和关系一致性层多个 Agent 的产物之间是否自洽比如实现里用到的字段都在接口定义里存在。第三层最容易漏也最容易出问题。我建议校验 Agent 的输出必须是一份可定位的差异报告精确到哪个字段、哪一行、期望什么、实际什么而不是笼统地说有问题。差异报告越精确修复 Agent 越好干活。6. 实测中的意外与经验那些文档不会写的事6.1 模型调用成本会以你意想不到的方式增长多智能体系统的成本不是线性的。角色越多、重试越多、上下文越大成本涨得越快。我实测过一个四角色链路正常跑一次的成本是单 Agent 的三到五倍一旦触发重试能到十倍以上。控制成本的关键不是砍角色而是砍无效上下文。每个 Agent 只给它完成任务必需的信息不要把整个共享状态一股脑塞进去。我见过最夸张的配置是把所有历史消息都拼进提示词成本高得离谱效果还更差因为模型被无关信息干扰了。6.2 并行不一定比串行快直觉上并行更快但实测经常相反。原因是并行 Agent 之间如果有隐式依赖比如都要读同一份共享状态会产生锁竞争和等待反而比串行慢。只有当子任务真正独立时才并行判断标准是两个 Agent 的输入集合有没有交集。有交集就老老实实串行。6.3 日志的可读性决定了你排查问题的速度多智能体系统的日志如果只是流水账排查问题时你会疯。我的经验是日志必须能回答三个问题谁、在什么时间、基于什么输入、产出了什么输出。最好给每条日志带一个全局 trace_id能把一次完整任务的所有消息串起来。这个投入在项目初期看起来多余出第一个疑难 bug 时你就知道值了。6.4 人工介入的口子一定要留再智能的系统也需要人工兜底。Agency Agents 里我建议在调度器里预留人工介入状态当自动修复连续失败、或者校验差异超过阈值时系统暂停并通知人来看。不要追求 100% 自动化追求自动化处理 90% 的常规情况把 10% 的疑难留给人这才是可持续的落地方式。7. 从能跑到好用几个让系统更稳的进阶配置7.1 给 Agent 加置信度输出让每个 Agent 在产出结果时附带一个置信度比如 0 到 1 的分数调度器据此决定是否需要额外校验。置信度低的产物自动触发二次校验置信度高的直接放行。这个机制能显著降低无效校验的开销同时不放过可疑结果。7.2 用影子运行验证新配置想调整某个 Agent 的提示词或调度规则别直接上线。让新旧配置同时跑对比两者的产物差异确认新配置确实更好再切换。这套影子运行的思路来自灰度发布在多智能体系统里同样适用能避免改一处崩全局。7.3 定期回放历史任务做回归把历史任务的消息序列存下来定期用新配置回放看结果是否退化。这相当于给协作系统做回归测试。我一般每周回放一批典型任务一旦发现某个改动导致历史任务结果变差立刻回滚。多智能体系统的改动影响面比单 Agent 大得多回归测试不是可选项。8. 我在这套系统上踩过的三个真实教训第一个教训关于过度拆分。我曾经把一个本来一个 Agent 就能干好的任务拆成三个理由是职责更清晰。结果三个 Agent 之间的消息传递和状态同步开销比任务本身还大整体耗时翻倍。后来合并回一个效率立刻回来。拆分的唯一理由是职责边界真的不同而不是看起来更专业。第二个教训关于契约先行。有个项目为了赶进度先让 Agent 自由发挥打算后面再统一接口。结果跑到一半发现各 Agent 的产物根本对不上返工的成本远超当初定契约的时间。契约这件事省下来的时间后面要加倍还回去。第三个教训关于可观测性投入。早期觉得日志和 trace 是锦上添花直到线上出了个偶发 bug没有 trace 根本复现不了排查了整整两天。从那以后我把可观测性当成第一优先级宁可功能少做一点也要把链路看清楚。这套 Agency Agents 的架构和落地经验说到底就一句话多智能体协作的难点从来不在智能而在协作。把角色边界划清楚、把接口契约定死、把调度规则显式化、把熔断和可观测做扎实剩下的模型能力问题反而好解决。反过来如果协作结构一塌糊涂再强的模型也只是在混乱里加速。