最近差不多两个月的时间我一直泡在一个内部研发辅助工具的重构项目里核心动作就是把它从单Agent模式改成多智能体协作系统内部代号就叫Agency Agents。听着有点绕但整体思路其实很朴素与其让一个大模型从头到尾包办开发任务不如像组建一支真实开发团队那样把需求拆解、方案设计、编码实现、代码评审、测试验收分别交给不同的Agent去干让它们各管一摊、互相配合。这个系统能做的事往小了说是自动把一个粗需求变成带测试的代码往大了说是提供一套可以复用的多智能体架构模板。文章里我会把架构设计、角色划分、协作机制、落地实操、踩坑记录一起整理出来适合正在研究多智能体应用、想在真实业务里把Agent用起来的工程师也适合刚入门、想搞清楚多智能体系统到底怎么落地的同学。1. 为什么用多智能体重构开发团队——核心命题与架构思路1.1 我是在什么场景下决定放弃单体Agent的先说改造前的状态。我之前那套工具就是典型的单体Agent把一大段需求描述、历史对话、相关代码片段全部塞进一个提示词里让大模型一口气输出完整代码。在demo阶段这套方案非常爽丢进去一句帮我写一个用户登录模块它真能给你吐出一堆能跑的文件。但只要碰真实项目问题就会接二连三地冒出来。第一个是上下文长度失控。一个正经需求通常涉及多个文件、多种约束、若干轮讨论把这些全塞进一个上下文窗口之后模型注意力会被严重稀释。表现为前半段还在认真按需求来后半段就开始放飞备忘录里提到的约束忘得一干二净。第二个是角色混乱。让同一个Agent既当架构师又当编码员还要自己审自己结果就是设计文档写得像代码注释、代码里又混进一堆设计讨论最后收拾起来极其痛苦。还有一个更隐蔽的问题单体Agent一旦输出中间结果是没有校验节点的错了就一路错到结尾中途没有任何机制能拦一下。真实开发团队里需求评审、代码评审、测试关卡都在不断拦截低级错误但单体Agent把这些环节全压缩了等于一个人又写代码又做测试出问题概率自然高。1.2 为什么拿开发团队当架构蓝图后来我意识到一个事情早在Agent出现之前软件开发行业就已经有一套成熟的复杂任务拆解方法论了也就是现代研发团队的组织方式。一个团队能稳定交付靠的不是某个人特别强而是下面这五个要素配合着运转分工产品、开发、测试各管一段职责边界清晰。流程需求到设计、设计到编码、编码到评审有先后顺序。评审代码有审查测试有验收错误在流转中被拦截。记录需求文档、接口约定、变更历史让信息可以跨阶段传递。工具CI、代码库、测试框架负责把琐碎的活自动化。多智能体系统如果把上面五条都落到架构里就是一套用Agent模拟的真实研发组织。这也是Agency Agents项目的核心命题不是搞一个什么都干的全能Agent而是造一批各有所长、按照固定协作协议配合的虚拟员工。1.3 架构模式怎么选三种主流方案的对比在动手之前我先梳理了多智能体的主流协作架构大概可以分为三类。流水线模式。需求Agent处理后把结果交给设计Agent再交给编码Agent像工厂流水线一样按顺序流转。好处是结构简单、可预测性强适合任务边界清晰的场景。坏处是上游一旦出错下游会一直错下去而且没法回头修正。编排者模式。也叫Orchestrator-Worker有一个中央调度者负责拆任务、派任务、收结果、做决策下面挂一堆专门干活的Worker。好处是控制力强编排者可以判断这个结果要打回重做或者下一步派给谁坏处是编排者的思维能力会变成瓶颈。协商模式。多个Agent地位平等通过讨论、投票、辩论达成共识。这种方式在需要多角度观点时表现亮眼比如让两个Agent扮演正方反方讨论一个技术方案。坏处是收敛慢、token消耗高、不可控。我做了一次对比选型最终选择的是以编排者模式为主、局部嵌入流水线执行的混合架构。核心调度由编排者Agent负责但执行路径是固定的流水线需求解析到设计到编码到评审到测试每个阶段完成后编排者根据质量门禁决定放行还是打回。这样既保住了流程稳定性又保留了分支决策能力。2. 智能体角色体系设计与开发团队的角色映射2.1 角色设计原则定岗定编比堆数量重要多智能体系统设计里最容易犯的错就是一上来搞十几个Agent感觉声势浩大结果系统连一个最小闭环都跑不通。我的经验是角色数量由任务链决定而不是由想象决定。先把一条完整任务链画出来标出必须的转换节点再给每个节点配一个Agent多余的统统砍掉。我给每个Agent定岗时遵守三条硬约束职责单一一个Agent只做一件事。比如审查Agent只做代码评审绝对不负责改代码让它顺带修一下只会让结果不可控。上下文最小化每个Agent看到的上下文只包含它做当前决策所需的信息不该看到的全局杂讯一律隔离。工具白名单每个Agent只挂自己需要的工具编码Agent有搜索代码和写文件的权限但测试Agent才有执行测试命令的权限。2.2 从需求解析到集成验收的角色全景顺着把粗需求变成已验收代码这条主链走下来我在Agency Agents里一共定义了六个角色。需求解析Agent。负责把用户模糊的描述转成结构化需求条目包括业务规则、验收标准、边界条件。它相当于真实团队里的产品经理输出的是一份可作为契约的需求清单。核心提示词约束是必须列出可验证的验收标准不能只写形容词。架构设计Agent。输入需求清单输出模块划分、数据流、接口定义、技术选型。它相当于架构师只做方案设计不写业务代码。关键约束是设计必须落到文件和函数级别以便后续编码Agent可以无脑实现。编码Agent。按照架构设计产出具体代码。它相当于开发工程师默认只会按设计执行遇到设计遗漏点时必须停下来向编排者上报而不能自作主张。这一点是我踩过坑之后加的硬性约束因为大模型太容易在不确定时帮你想当然了。代码审查Agent。负责从代码规范、逻辑缺陷、遗漏边界三个角度审查编码产出。它相当于评审组里的资深工程师输出是问题列表每条问题必须指出所在文件和风险等级。测试Agent。负责生成并执行测试用例包含单元测试和关键链路测试。它相当于测试工程师执行完测试以后输出测试报告对未通过项给出最少复现步骤。集成验收Agent。最后把关者把需求清单、代码、审查报告、测试报告放在一起做综合验收。只有它通过这轮任务才算结束。2.3 角色提示词的关键设计给Agent立人设不是写作文我为每个角色都写了一套固定结构的提示词这套结构经过多次调整后才稳定下来核心包含四块内容第一块是身份与能力边界明确你是谁、你能做什么、你绝对不能做什么。第二块是输入输出Schema严格规定输入字段和输出结构用JSON格式强制约束。第三块是工作流程提示描述你拿到输入后应该先看什么、再想什么、最后产出什么。第四块是公共铁律比如不得编造不存在的文件路径遇到歧义必须标记为待确认。下面给个简化版示例是编码Agent的核心提示词骨架你是该项目中的编码Agent职责是按照架构设计文档实现代码。 你可以访问的工具有代码库检索、文件写入。 你无权执行测试命令也无权修改架构设计文档。 输入是一个包含需求清单和模块设计的JSON对象。 输出必须是符合Schema定义的代码变更列表。 铁律 - 只实现设计文档中存在的模块不新增任何未要求的功能。 - 如果设计文档存在遗漏你必须以issue形式上报禁止自行决定实现方案。 - 所有代码必须包含异常处理。这套设计看起来简单但对稳定性提升是质变级的。角色边界一旦清晰Agent之间互相越权打架的情况就大幅减少了。3. 协作机制与通信协议——多智能体协同的核心关节3.1 任务怎么拆、怎么派编排者的任务分解策略编排者Agent承担了两项核心工作一是任务分解二是调度决策。任务分解上我采用的是渐进细化策略不在一开始就把所有子任务拆完而是沿着主流程逐级往下拆。拿到用户需求后编排者先生成一个宏观执行计划也就是先需求解析、再架构设计、再编码、再审查、再测试、最后验收这个顺序然后每进入一个环节再根据当前实际状态决定下一步怎么派活。这样做的好处是可以根据中间产物动态调整。比如审查Agent返回高危问题编排者可以选择打回给编码Agent而不是傻乎乎继续往测试阶段走。在代码层面我用的是一套简单的状态机每个Agent的执行状态有pending、running、passed、rejected四种编排者根据这些状态做路由。任务分发时每条消息都遵循统一结构包含任务ID、任务类型、输入数据、期望输出格式、最大轮次限制。这个结构的核心思路是让每个Agent把收到的任务和产出的结果都变成结构化消息而不是自由的对话文本结构化消息在传递和校验时都更可靠。3.2 共享记忆与状态管理短期会话与长期记忆的配合多智能体系统最容易翻车的地方在记忆设计。初期我天真的做法是让每个Agent把上一轮所有输出全文带进下一轮结果很快就发现上下文窗口撑不住而且大量无关信息会干扰Agent判断。后来我把记忆拆成了三层全局黑板、阶段产物、长期知识库。全局黑板只存放当前任务的高层状态包括用户需求摘要、当前所处阶段、各阶段结果的消息引用由编排者维护。阶段产物是每个Agent的输出也就是需求清单、设计文档、代码diff这些具体文件。长期知识库里存的是历史项目的决策记录和踩坑教训按需检索出来后注入相应的Agent上下文。这套三层结构的核心收益是隔离。编码Agent不需要看架构设计Agent审查自己时的长篇自我辩论记录它只需要拿最终的、通过校验的设计文档。隔离让每个Agent上下文保持精简也让上下文窗口溢出概率大幅下降。3.3 工具调用与安全边界给Agent装上带权限的手脚智能体不能只会说必须会动手。Agency Agents里的Agent都挂了一组工具但每个工具的使用权限是被编排者统一下发的。工具本身做得比较薄核心是三类代码类工具包括代码检索、文件读取、文件写入、git状态查看执行类工具包括运行测试、运行静态检查、执行构建脚本知识类工具包括长期记忆检索、需求文档查询。每一类工具都被包了一层沙箱Agent在沙箱里跑命令无法访问系统关键路径这样即使某个Agent被提示词注入攻击也无法对系统造成实质破坏。在实际运行中工具调用最常见的坑是Agent拿到一个错误输出之后反复重试同样的命令白白消耗token。所以我在工具层加了一个规则同一个命令连续失败两次后Agent必须如实上报失败原因而不是继续盲试。4. 落地实操从设计到实现的一次完整走读4.1 最小闭环目标只选了一条最有价值的链路在把六七个Agent全部接入之前我先框定了一个最小闭环用户输入一条模糊需求系统最终输出一份通过测试的代码变更并附带测试报告和审查报告。这条链路覆盖了需求解析、架构设计、编码、审查、测试、验收六个环节足够验证架构又不会一开始就被大而全的野心拖死。我给最小闭环定的验收标准非常直白代码能编译、测试能通过、需求清单里的验收标准有一一对应的代码实现。在这个标准面前任何花里胡哨的中间产物都没有意义。4.2 技术栈与关键组件选型先说基础模型。我选的是当前主流商用大模型的API出于成本和稳定性考虑需求解析和架构设计这种偏理解的任务用较高智能档位的模型简单执行类任务可以用速度更快、成本更低的档位。模型分层这件事我强烈建议所有做多智能体的人都认真对待它带来的成本收益差距是数量级的。编排框架我没有自己从头造轮子而是基于一个支持图状态编排的开源Agent框架来搭。选择它的原因有两点一是它天然支持节点和边的图结构跟我的流水线加分支思路一致二是它内置了状态持久化功能节点之间传消息不会丢。另外需要一个向量库来做长期知识库检索。这里我选了轻量级的本地向量方案因为项目规模不大没必要为了demo上重服务。4.3 核心编排逻辑用伪代码拆给你看编排者是整个系统的心脏它的核心逻辑其实不复杂。我把核心调度流程用伪代码还原出来这是经过实际裁剪的版本但保留了主干class AgencyOrchestrator: def __init__(self): self.agents { requirement: RequirementAgent(), architect: ArchitectAgent(), coder: CoderAgent(), reviewer: ReviewerAgent(), tester: TesterAgent(), integrator: IntegrationAgent(), } self.state GlobalState() self.max_retry 2 def run(self, raw_request): # Step 1: 需求解析 req_result self.run_with_retry(requirement, raw_request) if not req_result.passed: return failed(需求解析失败) self.state.requirement req_result.output # Step 2: 架构设计 design_result self.run_with_retry(architect, self.state.requirement) if not design_result.passed: return failed(架构设计失败) self.state.design design_result.output # Step 3: 编码 code_result self.run_with_retry(coder, { requirement: self.state.requirement, design: self.state.design, }) if not code_result.passed: return failed(编码失败) self.state.code code_result.output # Step 4: 审查与迭代 for attempt in range(self.max_retry): review_result self.run_agent(reviewer, self.state.code) if review_result.has_high_risk: self.state.code self.run_agent(coder, self.state.code review_result.output) else: break # Step 5: 测试 test_result self.run_agent(tester, self.state.code) if not test_result.all_passed: return failed(测试未通过原因: test_result.failed_reasons) # Step 6: 集成验收 accept_result self.run_agent(integrator, { requirement: self.state.requirement, code: self.state.code, review: review_result.output, test: test_result.output, }) return success(accept_result.output)这段代码里有几个细节值得展开。run_with_retry是我封装的一个重试机制如果Agent输出不符合Schema、或者返回明确错误就带上错误信息重试一次。重试后的结果如果还不行就直接失败。这比无脑循环要安全得多因为大模型在同一个问题上连续失败两次第二次往往只是换一批措辞接着错意义不大。审查与迭代那一轮循环是我反复调整过的设计。最初的版本是审查Agent发现问题后直接返回文本让编排者人工判断后来发现文本形式的信息不好做路由于是改成让审查Agent输出结构化问题列表每条带风险等级编排者只检查是否存在high级别问题来决定是否打回。4.4 一次实际运行记录与关键数据复盘为了验证这套系统我找了一个内部模拟项目X的需求做测试。需求原文是做一个带过期时间的缓存模块支持LRU淘汰策略并提供并发安全的读写接口。这个需求看似清楚但隐藏了不少边界问题比如过期时间精度、LRU的并发实现、缓存容量超过限制时的行为。整条流水线跑下来耗时大约6分钟token消耗约12万。需求解析Agent产出了14条验收标准其中有一条我一开始以为它过度解读了仔细看才发现确实有道理它把并发安全的读写接口扩展成了读操作不能阻塞写操作太长时间这其实是缓存模块常见的隐藏需求。架构设计Agent选择了二级缓存结构L1用哈希表加LRU链表L2用时间轮处理过期任务。这个方案算得上中规中矩但第一次编码实现的时候编码Agent把时间轮的实现写复杂了还引入了一个不存在的泛型类型。代码审查Agent准确抓到了这个问题标为高危并打回。重做之后测试Agent生成的12个测试用例里有11个通过最后挂掉的那个是并发写入的极限压力测试原因是锁粒度太粗。测试报告反馈之后编码Agent做了一次针对性优化把锁拆细全部测试通过。这个案例给我的最大启示是多智能体的价值不只是并行干活更重要的是让错误在更早的节点被拦截。如果还是单体Agent那个不存在的泛型类型很可能就带着走到最后一版代码里了。4.5 参数配置心得temperature、最大轮次与输出约束大模型的生成参数对多智能体系统稳定性影响很大。我给不同角色设置不同的采样参数整体原则是理解类任务宽松、执行类任务严格。需求解析和架构设计这类创造性任务的temperature放到0.4左右让模型有一定发散度能生成多角度方案。编码和审查这类精确任务的temperature压到0.1甚至0尽可能减少幻觉。测试Agent的temperature也压得很低因为测试用例需要严谨。还有一个参数值得提输出token上限。如果不给Agent设置合理的max_tokens经常会出现输出被截断到一半、生成的JSON无法解析的情况。我在每个节点的调用里都显式传了max_tokens核心节点要求输出必须完整宁可多花一点成本也不允许截断。实践下来因为截断导致的重试次数大幅下降。5. 常见问题与排查技巧实录5.1 上下文污染Agent精神分裂了怎么办我在早期版本碰到过很诡异的场景编码Agent在第3轮迭代时突然在代码里写入了跟需求毫无关系的注释而且语气像在跟另一个Agent对话。排查后发现原因是我把前几轮审查Agent的原始输出直接拼到了编码Agent的上下文里里面包含了一些建议你重新考虑设计这类对话性内容结果编码Agent真的被带偏了。这个问题的解法是引入消息摘要替换全文拼接。具体来说进入编码阶段之前编排者先让一个轻量Agent把之前的长对话压缩成三条信息确认通过的设计要点、待处理的审查问题、本轮必须完成的变更目标。编码Agent只读这三条不再接触原始讨论。这个改造上线后上下文污染类问题基本绝迹。5.2 死循环与状态机失控如何打断不收敛的重复劳动有一轮测试让我印象很深系统卡在审查打回—编码重改—审查再打回的循环里出不来。每次编码Agent改完审查Agent都能找到新问题而且这些问题难度逐次下降但始终归不了零。后来我在编排层加了三道保险。第一是最大迭代轮次限制单个审查-编码循环最多两轮超过后强制进入降级路径第二是问题相似度检测如果两轮审查输出里有一模一样的问题描述就判定当前Agent组合无法解决直接上报第三是阶段超时熔断整个任务设置总时间上限超时自动结束并导出当前中间产物。这三级保险上线之后不收敛的情况就再也没有拖垮过系统。5.3 Token消耗爆炸多智能体系统烧钱太快怎么办多智能体系统的token消耗远超单Agent这是很多人在落地时第一个喊疼的地方。我在一次全量测试里统计过系统跑一轮完整流程的平均token成本是单体Agent方案的三到五倍。如果不加控制成本会直接劝退。成本控制上我有几个实际有效的招。第一个是阶段性摘要这个前面提过不再赘述第二个是按角色分配模型档位需求解析用旗舰模型编码用中端模型测试用轻量模型整体成本能降到全旗舰方案的一半左右第三个是精简Agent上下文我专门写了一个字段过滤器每个Agent只能拿到它需要的字段其余全不传递。算下来这三招叠加把单任务成本压到了可接受的范围而质量几乎没有明显下降。5.4 协作产出质量如何度量没有评测就是盲人摸象多智能体系统是不是真的比单Agent强不能靠感觉必须量化。我给系统建了一套三层评测指标。第一层是任务成功率看整条流水线最终产出能否通过验收。第二层是单节点通过率分别统计需求解析、架构设计、编码、审查、测试各阶段的独立通过率这层指标能快速定位瓶颈到底在哪个Agent。第三层是缺陷拦截率统计审查和测试阶段实际拦截到的高危问题数量多智能体的核心价值就体现在这里。跑了几轮基线评测之后我发现单节点的瓶颈往往不在输出质量而在输入质量。比如编码Agent输出不稳定很多时候是因为架构设计Agent给的输入不够具体。这让我开始重视每个阶段的产物校验而不是一味责怪某个Agent能力不行。6. 一点个人体会与扩展方向回到标题里重构开发团队这个说法我的体会是多智能体系统真正改变的并不是一个Agent变成一个团队这种表面形式而是让系统拥有了开发团队里那种相互校验的张力。单Agent再强也不会自己质疑自己而多Agent如果设计得当审查Agent会把编码Agent的问题拦下来测试Agent又会把审查Agent没发现的漏洞捞出来这种互相纠错的机制才是多智能体架构最有价值的部分。如果让我给想尝试的人一条最重要的建议我会说先手动跑通流程再谈自动化。我第一次搭这套系统时先用人工把六个环节完整走了一遍记录下每个环节输入输出长什么样然后再让Agent去复现这些接口。很多架构问题是走完这一步才暴露出来的比如消息结构里缺少任务ID、阶段产物没有版本概念这些问题如果不手动跑一遍根本反应不过来。最后再分享一个小技巧。在多智能体系统里我后来给每个Agent的输入都加了一个固定前置字段你正处在整个任务流程的第X步前序步骤已完成你仅需聚焦你负责的环节。这个看似多余的提示对减少Agent越界行为有奇效。别小看这种话在长链条任务里一次小小的越界就可能导致整条链路的输出变得不可控。