我花了两周时间把一个需要四个人并行开发的内部项目硬生生塞给了一组 AI Agent。说出来你可能不信最后跑通的产出质量比我团队里两位中级开发交出来的第一版都要干净。这个想法不是拍脑袋冒出来的。当时我手里压着两个并行需求团队能写代码的人已经连续加班到晚上十点。我把主流的 AI 编码辅助工具挨个试了一圈发现它们最大的问题不是写不出代码而是永远在单打独斗你给一个模糊需求它就猜一个实现方式你让它改接口它不会主动去同步调用方更没有人做需求澄清和代码审查。这让我意识到把开发工作交给 AI关键不在于单个 Agent 有多聪明而在于能不能把一套开发流程拆成多个角色让它们像真实团队一样协作。于是就有了这套 Agency Agents 多智能体协作系统的原型。这套东西的定位很明确不是给个人用的补全工具而是一个能承接完整需求、独立跑完需求分析—技术设计—编码—测试—审查全流程的轻量级虚拟开发团队。如果你也在纠结怎么把手头的编码工作流改造成多智能体协作模式或者被 Agent 之间互相抢活、上下文混乱的问题折腾得头大这篇文章值得你花十五分钟看完。1. 为什么好好的团队会想着交给一堆 Agent1.1 从帮你写代码到替你拆任务大部分人对 AI 编程的认知还停留在对话式补全打开编辑器写一段注释让 AI 填出函数体。这种模式有两个天花板。第一是上下文窗口不够用。单个 Agent 的注意力是有限的你让它负责整个项目它会在前 2000 行代码里表现优秀到了第 5000 行就开始自相矛盾忘了前面的模块接口长什么样。第二是责任边界模糊。真实团队里写接口的人和改调用方的人可能是两个角色但在单 Agent 模式下它既当产品经理又当测试角色冲突导致它经常在实现需求和怀疑需求之间内耗。多智能体协作解决的就是这两件事。通过把项目拆成若干独立角色每个 Agent 只维护自己负责的上下文片段控制上下文长度同时把分析需求和写代码分成两个 Agent让需求变更不至于直接冲击编码过程。用一句大白话讲单 Agent 是一个人干所有活儿多智能体是一群人各管一摊活儿。1.2 多智能体协作的适用边界我必须先泼一盆冷水不是所有项目都适合上多智能体。我这套系统跑得顺前提是项目形态非常适合它。适合的场景有三个共同特征。第一需求边界相对清晰可以拆成独立任务比如内部后台系统、报表工具、定时任务脚本第二交付物以代码和文档为主不需要和外部硬件或者真人反复交互第三团队对代码风格和接口规范有明确约定这样不同 Agent 产出的代码才能拼得起来。不适合的场景也很清楚涉及强交互的 UI 原型评审、需要线下资源协调的项目、需求三天两头大改方向的探索型业务这几种情况别硬上。Agent 处理需求变更的能力比真人差远了你让它重写一个模块它大概率会把另一个模块的代码也顺手带偏。提示上多智能体之前先把你要做的项目拆成一张任务清单。如果这张清单超过三成任务需要互相等待那说明项目依赖关系太强不太适合当前阶段的多智能体协作。2. 系统架构我把团队拆成了哪几层2.1 整体拓扑与角色分工我的系统没有用复杂分布式架构就是一层很朴素的调度中心加六类执行单元。调度中心负责拆任务、分派、收集结果执行单元是六个不同角色的 Agent每个角色有独立的提示词和工具权限。产品 Agent接收原始需求输出功能列表、验收标准和优先级架构 Agent把功能映射到模块定义接口、数据结构和跨模块调用关系后端 Agent按照架构设计实现服务端逻辑前端 Agent基于后端接口实现调用方和页面逻辑测试 Agent根据验收标准生成测试用例并实际执行审查 Agent检查代码规范、安全风险和设计一致性这个角色划分不是拍脑袋定的我参考了自己团队的真实岗位设置。关键原则是每个角色的职责不能重叠。比如架构 Agent 只画接口不写实现后端 Agent 只负责实现不改需求描述。职责一旦重叠多个 Agent 就会对同一件事产生不同判断最后产出的模块互相打架。2.2 通信模式共享黑板而不是微信群多智能体系统最核心的设计决策不是用什么模型而是 Agent 之间怎么通信。我见过很多方案用消息满天飞模式每个 Agent 之间直接发消息像一个热闹的微信群。这种模式在三个 Agent 时听起来很美但 Agent 数量到五个以上就会失控消息延迟、上下文重复、多个 Agent 同时抢改一个文件。我采用的是共享黑板模式。所有 Agent 不直接对话而是把产出写到一块共享工作区里调度中心负责维护黑板上的内容版本。比如产品 Agent 写完需求文档黑板上的需求文档就更新后端 Agent 开始编码前去黑板上读最新的接口定义而不是靠消息告诉你接口改过了。这对应到项目里就是一个共享文件目录加一份状态索引。每个 Agent 有权限读写自己的产物目录但读取他人产物时只能读取不能修改。这个权限设计非常重要它是防止 Agent 之间互相覆盖劳动成果的关键。2.3 任务编排串行推进 反馈回路任务不能一口气全发出去。产品分析、架构设计、后端编码、前端编码、测试这些阶段有严格的先后依赖。我采用了一个带反馈回路的串行流水线。调度中心把流程定义成一个有向无环图产品完成才能开始架构架构完成才能分配前后端任务前后端完成后测试才能开始。这避免了多个 Agent 抢在依赖未完成的情况下盲目开工。但光串行会有一个致命问题如果测试发现后端接口和前端调用不一致整个流程就卡死了。所以我加了反馈回路。测试 Agent 发现的缺陷不会直接打回给开发而是先回到架构 Agent 做原因分类是设计问题还是实现问题。这样避免两个开发 Agent 因为同一个缺陷互相推诿循环重试。我实测下来单个项目的平均执行链路是 6 个阶段其中平均会触发 1.8 次反馈回路。也就是说完全一次通过的项目是少数多数项目都要经历一轮来自测试或者审查 Agent 的返工。这不是缺陷反而是多智能体协作的价值所在——它用额外的计算成本换来了质量的自我修正。3. 核心环节实现代码层面怎么落地3.1 Agent 的基础抽象说完了架构思路直接上核心代码。我这里的 Agent 不复杂核心就是一个带角色属性、工具权限、输出产物路径的执行函数。它内部还是调用大模型但多了两层约束角色提示词和产物校验。from dataclasses import dataclass, field from enum import Enum from typing import Optional class AgentRole(Enum): PRODUCT product ARCHITECT architect BACKEND backend FRONTEND frontend QA qa REVIEWER reviewer dataclass class Task: task_id: str role: AgentRole description: str input_paths: list output_paths: list status: str pending # pending/running/success/failed result: Optional[str] None retry_count: int 0 dataclass class Agent: role: AgentRole system_prompt: str allowed_tools: list model: str max_retries: int 3 def execute(self, task: Task) - Task: context self._collect_context(task.input_paths) prompt self._build_prompt(task.description, context) result self._call_model(prompt, self.system_prompt) task.result result task.status success return task这里有两个细节值得说。第一每个 Agent 都有独立的system_prompt这是角色行为约束的核心。第二_collect_context只读取input_paths指定的文件读取范围被严格控制避免 Agent 看到不该看的内容而产生偏见。3.2 角色提示词的设计角色提示词是我踩坑最多的地方。一开始我写得又长又绕结果产品 Agent 开始写代码后端 Agent 开始谈需求。后来我总结出一套三段式提示词结构角色定位用一句话说明你是谁、为谁服务、对接谁工作方式说明你输入什么、输出什么格式、遵循什么约束避坑约束明确列出你不该做的事情以架构 Agent 为例你是一名系统架构师负责把产品需求转化为可实施的技术设计方案。 输入需求文档来自产品 Agent 输出接口定义文档、数据模型定义、模块划分文档、技术选型结论 约束 - 只设计接口不写业务实现 - 接口定义必须包含每个参数的名称、类型、取值范围 - 技术选型只允许从既定技术栈里选择 - 如果产品需求存在歧义在文档中标注待确认不要自作主张这段提示词看着简单但只设计接口不写业务实现这句话省了我不计其数的返工。并且要在每个角色提示词里加一句如果你发现上游输入有问题暂停并提交问题说明而不是继续执行。这是防止幻觉扩散的第二道防线。3.3 上下文与状态管理多智能体系统最常见的故障不是模型答错而是上下文越滚越大最后 Agent 只盯着最近对话忘了项目背景。我用了两级记忆机制。第一级是项目级记忆存在共享目录的PROJECT.md里记录项目目标、技术栈、模块树、历史决策。所有 Agent 在执行前都会读这个文件但不写入。第二级是任务级记忆每个 Agent 只保留自己这次任务相关的上下文执行完毕就释放。任务级记忆使用了摘要压缩策略当单次任务的上下文超过模型窗口的 70% 时就把早期内容压缩成摘要作为前缀保留。这样能稳定地把单任务上下文控制在 4000 token 内整个项目六七个 Agent 跑完不会出现上下文互相污染。3.4 质量闭环审查、重试与失败降级质量保障不能只靠一个测试 Agent。我在流水线末端加了一个独立的审查 Agent它的任务是检查后端和前端产出的代码是否满足架构 Agent 定义的接口规范以及是否存在明显安全问题。审查 Agent 的输出是两类问题的列表阻断问题和建议问题。阻断问题丢回对应开发 Agent 重试建议问题写入项目日志但不影响上线。这个机制看起来很简陋但它带来了一个关键收益重试不是无限的。每个任务设置了最大重试 3 次超过次数就触发失败降级由调度中心输出一个未完成任务报告人工介入。4. 实操全过程用模拟项目跑通整个系统4.1 环境与依赖整套系统跑在 Python 3.11 上依赖极少。核心就用了一个异步 HTTP 客户端、文件操作库和一个 YAML 配置解析器。没有引入额外的 Agent 编排框架这是刻意为之。我想先验证多智能体协作的核心逻辑不想被框架限制。模型方面我统一调用一个成熟大模型的接口通过配置文件切换角色对应的模型版本。实际跑下来产品分析、架构设计这类推理任务用稍大一点的模型效果更好前后端编码用普通模型就够测试 Agent 倒是意外地吃模型能力因为它要同时理解需求和代码两边的语义。4.2 搭建共享工作区与协调器共享工作区就是一个目录我在里面建了五个子目录对应五类产物。调度协调器是一个不到 300 行的 Python 脚本作用是把任务队列按依赖关系排序、逐个分派、收集结果。import asyncio from pathlib import Path class Scheduler: def __init__(self, agents, workdir: str): self.agents agents self.workdir Path(workdir) self.task_queue [] def build_plan(self, raw_requirement: str): # 根据项目模板生成任务依赖图 pass async def run(self): for task in self.task_queue: agent self.agents[task.role] task agent.execute(task) if task.status failed and task.retry_count agent.max_retries: self.task_queue.append(task) # 重新排队 return self.generate_report()关键点是任务重排队逻辑。失败的任务不是原地重试而是丢回队列末尾这样避免同一个失败任务卡住后面所有任务。4.3 一次完整执行记录我挑一个有代表性的模拟项目来展示执行过程。需求是为内部项目管理系统增加报表导出功能支持按日期范围导出 CSV 文件并发送到配置的邮箱。第一阶段产品 Agent 输出了功能清单新增导出页面、按日期筛选、生成 CSV、异步发送邮件、导出历史记录。验收标准有 7 条其中一条是CSV 必须支持 UTF-8 编码兼容 Excel 打开。第二阶段架构 Agent 定义了接口/api/v1/reports/export参数是start_date、end_date、email响应里带一个task_id用于异步查询导出状态。它特意标注了待确认项要求产品确认超过 10 万条数据时的导出策略。第三阶段到第五阶段前后端编码和测试执行了约 40 分钟含调用等待时间。测试 Agent 生成了 6 条测试用例其中一条 CSV 的 UTF-8 编码测试第一次跑失败了。原因是后端 Agent 写了标准的文件输出但没有加 BOM 头。这个缺陷被打回后端第二次修复通过。最后审查 Agent 发现了一个阻断问题CSV 字段拼接时没有处理单元格内包含逗号的转义场景。这个虽然有争议因为当前需求里字段列表固定不含逗号但审查 Agent 按规则把它标记为阻断后端重试后加了双引号包裹逻辑。整个流程到此结束耗时约 70 分钟产出代码大约 600 行前后端各 300 行。4.4 成本估算与参数调整跑完这套流程最直观的成本是大模型 API 调用费。我按一次完整项目做了统计角色调用次数平均单次输入 token平均单次输出 token产品 Agent23500800架构 Agent342001200后端 Agent460002500前端 Agent355002200测试 Agent370001800审查 Agent255001500总计约 13 万 token 左右。如果模型单价较高一次完整项目约几元成本相比真人写 600 行代码的成本算下来还是相当划算的。参数调整上最有用的一个旋钮是测试 Agent 的严格程度。我把测试 Agent 的提示词里加了一句如果你认为需求描述存在明显遗漏必须在测试用例中体现为未通过项整个系统的输出质量立刻上了一个台阶。因为测试 Agent 松弛的话下游审查 Agent 再严也只是捡漏。5. 踩坑实录多智能体的十个常见问题5.1 高频问题速查表跑了两周我整理了出现频率最高的问题做成一张速查表现象根因解决方式后端写的接口和前端调用不一致共享黑板上接口文档修订后后端没重新读取每次任务执行前强制刷新依赖文件多个 Agent 同时修改同一文件产物路径颗粒度太大细化物产目录一个文件一个职责Agent 过度返工来回横跳反馈回路没有做原因分类增加架构 Agent 对缺陷的分类环节上下文越滚越大回答质量下降没有做摘要压缩单任务 token 超 70% 时压缩历史需求变更传递失真需求 Agent 没有在黑板中标注变更影响面需求变更必须附带影响范围说明5.2 最值得警惕的三个隐形坑第一是幻觉扩散。单个 Agent 偶尔会编造一个不存在的接口名称这不算严重因为人类也会犯。但可怕的是后端 Agent 编造了一个接口getExportStatus前端 Agent 读黑板时发现这个事实存在就会顺着去调用。系统内部因此形成了高度一致的共识错误。最后是审查 Agent 对照架构文档才揪出来的。所以架构 Agent 的定义文档必须被设为最高权威其他 Agent 的产物都要和它对拍。第二是无反馈的死循环式完稿。如果审查 Agent 一次性列出了 10 个阻断问题后端 Agent 会进行一次大规模重写但重写后往往会引入新的非阻断问题导致又来一轮审查。解决方法是限制定量修改每次重试只允许修复审查列出的问题不允许顺手重构其他代码。这个约束在提示词里写了三遍不然一定会出乱子。第三是测试通过率和真实上线质量的错位。测试 Agent 写的测试用例往往是基于它自己生成的种子数据这些种子数据过于干净导致测试通过率虚高。我给测试 Agent 加了一个混乱数据注入工具让它至少在测试数据里加入 20% 的空值、重复值、边界值。这套改进之后测试环节发现问题的数量增加了大概一倍。注意多智能体系统的测试比单 Agent 更需要关注数据的多样性。干净数据下的绿色测试往往只是给交付一个虚假的安全感。6. 从这套系统里我悟到的三件事第一多智能体的价值不在于让每个 Agent 变强而在于让它们互相校对、互相兜底。单一模型再聪明也躲不过上下文遗忘但架构文档锚定 测试返工 审查拦截的三个环节可以把质量波动死死按在可控范围内。第二系统调试的重心应该放在协作协议上而不是单个 Agent 的提示词上。我花在调度、黑板、任务依赖上的时间远多于调某个角色的提示词。角色提示词写得再完美协作协议不通畅产出依然是一堆拼不起来的碎片。第三多智能体的落地本质上是把团队的隐形流程显性化。你平时怎么开需求评审会、怎么做接口联调、怎么设测试通过标准这些规则如果说不清楚Agent 更不可能执行到位。所以下一步我会把这套系统往实时交互的方向扩展让产品 Agent 在需求不明确时可以直接向使用者提问而不是只能写一个待确认了事。这里面还有不少坑要踩等跑通了再回来分享。