1. 从agency-agents这个标题说起一个多智能体协作框架的完整拆解第一次看到agency-agents这个标题的时候我脑子里蹦出来的第一反应是这大概率是一个围绕代理和智能体做文章的项目而且从命名习惯来看它很可能是把agency代理机构、中介、能动性和agents智能体、代理者这两个概念揉在一起指向的应该是一套让多个智能体像一家公司或一个团队那样协同工作的系统。这个判断不是拍脑袋来的——在最近一两年的技术圈里多智能体协作已经从一个学术概念快速下沉成了工程实践越来越多的开发者开始尝试把单个大模型包装成有角色、有职责、有工具的智能体然后让它们组队干活。而agency这个词本身就带着能动性和代理关系的双重含义放在这个语境下几乎可以确定它想表达的是让智能体具备自主决策和分工协作的能力而不是单纯地一问一答。我之所以对这个方向特别有感触是因为我自己在过去大半年里陆陆续续搭过好几套类似的多智能体小系统踩过的坑可以说是一箩筐。最开始我以为只要把几个提示词拼在一起让模型轮流发言就行了结果发现根本不是那么回事——智能体之间会互相甩锅会陷入无限循环的讨论会在没有明确终止条件的情况下一直聊下去。后来我才慢慢意识到多智能体系统的核心难点从来不是让它们说话而是让它们有组织地说话。这就像你开一家公司招了一堆能力很强的人但如果没有明确的岗位职责、汇报关系和决策流程这帮人凑在一起只会互相扯皮产出还不如一个人单干。所以这篇博文我想借着agency-agents这个标题把多智能体协作框架这件事从头到尾讲透。我会聊清楚它到底解决什么问题、核心架构应该怎么设计、每个关键环节的实现要点在哪里、以及我在实操中遇到的那些文档里不会写的坑。不管你是刚听说多智能体这个概念的新手还是已经动手搭过一两个 Demo 但总觉得哪里不对劲的开发者我都希望这篇内容能给你一些可以直接抄作业的东西。我不会堆砌那些听起来很唬人的术语而是尽量用大白话把原理讲明白再配上能跑起来的思路和参数选择的依据。2. 多智能体协作到底解决什么问题先想清楚为什么再动手怎么做2.1 单智能体的天花板在哪里在聊多智能体之前必须先承认一个事实单智能体在很多场景下已经够用了。你给它一个明确的指令它调用一两个工具返回一个结果这个链路是清晰可控的。但一旦任务变得复杂单智能体就会暴露出几个明显的短板。第一个短板是上下文窗口的物理限制。一个复杂任务往往需要查阅大量资料、处理多个子问题、维护中间状态这些信息全塞进一个上下文里很快就会把窗口撑爆。你可能遇到过这种情况让模型处理一份很长的文档前面几段它还记得到后面就开始失忆甚至把前面已经确认过的结论给推翻了。这不是模型笨而是它的工作记忆就那么大。第二个短板是角色冲突。同一个模型既要当研究员去发散地搜集信息又要当审核员去严格地挑毛病这两个角色的思维模式是打架的。你让它发散它就收不住你让它严谨它又不敢大胆假设。这种内在矛盾会导致输出质量不稳定时而天马行空时而畏首畏尾。第三个短板是错误累积。单智能体是一条直线走到底中间任何一步出了偏差后面就会一路错下去而且它自己很难发现。因为没有第二双眼睛来交叉验证错误会像滚雪球一样越滚越大。2.2 多智能体协作的核心价值多智能体协作的本质是把一个复杂任务拆解成若干个相对独立的子任务每个子任务交给一个专精的智能体去处理然后通过一套协调机制把它们串起来。这样做的好处我用一个生活化的类比来解释单智能体就像一个全能但精力有限的自由职业者什么都能干一点但什么都干不精多智能体则像一家分工明确的小公司有负责调研的、有负责执行的、有负责质检的每个人只专注自己那一块整体产出反而更稳定。具体来说多智能体协作带来的价值体现在三个层面。第一是专业化分工每个智能体只需要关注自己领域的提示词和工具集提示词可以写得更精细工具可以配得更精准不用在一个提示词里塞进互相矛盾的要求。第二是并行处理多个独立的子任务可以同时跑整体耗时能大幅压缩这在处理批量任务时优势特别明显。第三是交叉验证一个智能体的输出可以被另一个智能体审查这种互查机制能有效拦截很多低级错误。2.3 什么场景适合上多智能体不是所有任务都值得上多智能体杀鸡用牛刀反而会增加复杂度和成本。根据我的经验下面这几类场景上多智能体是划算的任务可以清晰拆解成多个阶段比如调研→分析→撰写→审核这种流水线式的流程。需要多种视角或角色比如既要有人提创意又要有人做可行性评估。单个任务的上下文量很大需要分而治之避免窗口溢出。对输出质量要求高需要交叉验证来降低错误率。反过来如果任务很简单、一步就能搞定或者子任务之间耦合度极高、根本拆不开那还是老老实实用单智能体别给自己找麻烦。我见过不少项目明明一个提示词能解决的事非要搞五六个智能体来回传话结果延迟翻了好几倍效果还没提升这就是典型的过度设计。3. 核心架构设计一个多智能体系统应该长什么样3.1 角色定义每个智能体的岗位说明书多智能体系统的第一步也是最关键的一步是定义清楚每个智能体的角色。我习惯把这一步叫做写岗位说明书因为它和公司招聘的逻辑几乎一模一样。一个合格的岗位说明书要包含四个要素职责范围、能力要求、可用工具、输出格式。职责范围决定了这个智能体该管什么、不该管什么。这里有个常见的坑很多人喜欢把职责写得很宽泛比如你是一个助手负责帮助用户解决问题。这种描述等于没说智能体根本不知道自己该聚焦在哪里。正确的做法是写得足够具体比如你是一个资料检索员你的唯一职责是根据给定的关键词从知识库中找出最相关的三条信息并标注来源。职责越聚焦智能体的表现越稳定。能力要求其实就是提示词里的角色设定和约束条件。我会明确告诉它你擅长什么、你不擅长什么、遇到不确定的情况应该怎么办。比如对于审核员角色我会写你的职责是挑毛病如果找不到问题你必须明确说明未发现明显问题而不是强行编造问题。这一条特别重要因为模型有讨好倾向你让它找问题它有时候会为了交差而硬凑。可用工具决定了这个智能体能调用哪些外部能力。这里的原则是最小权限——只给它完成本职工作必需的工具不要图省事把所有工具都开放给所有智能体。原因很简单工具越多模型选错工具的概率越大而且一旦某个智能体越权调用了不该它用的工具排查起来会非常痛苦。输出格式是很多人忽略的一环但它直接决定了智能体之间能不能顺畅交接。如果上游智能体输出的是一段自由文本下游智能体就得花大量精力去解析还容易解析错。我的做法是强制所有智能体按照结构化格式输出比如 JSON 或者带明确标记的文本块这样下游可以直接读取字段不用猜。3.2 通信机制智能体之间怎么对话智能体之间的通信机制是整个系统里最容易出问题的地方。我踩过的坑包括消息格式不统一导致解析失败、消息丢失导致流程卡死、消息循环导致无限对话。要避开这些坑需要在设计阶段就把通信协议定清楚。我推荐的做法是采用中心化的消息总线模式而不是让智能体之间点对点直接通信。所谓中心化就是所有消息都先发到一个调度中心由调度中心决定这条消息该转给谁。这样做的好处是消息流向清晰可追踪出问题了容易定位可以统一做格式校验不合规的消息直接打回方便做限流和超时控制避免某个智能体卡住拖垮全局。消息本身的结构我一般会定义成固定的几个字段发送者、接收者、消息类型、负载内容、时间戳、以及一个用于追踪整条链路的会话 ID。会话 ID 这个字段看起来不起眼但在排查问题时是救命的——你可以用它把一次完整任务的所有消息串起来一眼看出是哪一步出了岔子。提示通信协议一定要在写代码之前就定死并且写成文档。我吃过亏一开始图快边写边改协议结果后面几个智能体对不上返工花的时间比一开始认真设计多得多。3.3 调度策略谁来决定下一步干什么调度策略决定了整个系统的大脑在哪里。常见的策略有三种固定流程、动态路由、混合模式。固定流程就是提前把执行顺序写死A 做完交给 BB 做完交给 C。这种策略最简单、最可控适合流程稳定的场景。缺点是灵活性差遇到预料之外的情况没法应对。动态路由是让一个调度智能体根据当前状态决定下一步该谁上。这种策略灵活能应对复杂情况但风险也大——调度智能体本身可能判断失误而且它的决策过程不透明出问题了不好排查。混合模式是我个人最推荐的主干流程用固定顺序保证稳定性在关键的分支点引入动态判断。比如调研→分析→撰写这个主干是固定的但在分析环节如果发现资料不足就动态触发一次补充调研。这样既保证了整体可控又保留了一定的应变能力。3.4 状态管理怎么记住我们进行到哪了多智能体系统跑起来之后会产生大量的中间状态已经完成了哪些步骤、每个步骤的产出是什么、当前卡在哪里、有没有重试过。这些状态如果管理不好系统就会失忆重复劳动或者漏掉步骤。我的做法是维护一个共享状态对象所有智能体都能读取但只有特定的智能体有写入权限。这个状态对象里至少要有任务 ID、当前阶段、各阶段产出、重试计数、以及一个全局的是否完成标志。共享状态的好处是任何一个智能体接手时都能快速了解全局情况不用靠猜。这里有个细节要注意状态对象不要无限增长。如果每个智能体都把完整的对话历史塞进去很快就会撑爆。我的经验是只保留结论性的状态比如调研阶段产出了三条关键信息而不是把调研过程中的每一句话都存下来。需要细节的时候再去查对应的日志。4. 实操落地从零搭一个多智能体协作流程4.1 环境准备与基础依赖动手之前先把基础环境理清楚。多智能体系统本质上是对模型接口的编排所以核心依赖就是模型调用能力、一个能跑异步任务的语言环境、以及一个轻量的状态存储。语言环境我推荐用 Python因为它的异步生态成熟写并发调度很顺手。核心依赖库包括用于调用模型的 SDK、用于异步调度的 asyncio、用于数据校验的 pydantic用来定义消息和状态的结构避免字段错乱、以及一个轻量的本地存储比如 SQLite 用来持久化状态。如果你打算跑在服务端再加一个 FastAPI 做接口层就够了。配置管理这块我要特别提醒一句所有模型相关的参数都要抽到配置文件里不要硬编码在代码里。因为多智能体系统调参是家常便饭温度、最大 token 数、超时时间这些参数不同角色可能需要不同的值。硬编码的话改一次参数就要改代码、重新部署效率极低。我一般用一个 YAML 文件管理所有角色的配置改完重启即可生效。4.2 定义第一个智能体从调研员开始我习惯从调研员这个角色开始搭因为它的职责最清晰最容易验证。调研员的任务是接收一个查询从指定来源检索信息返回结构化的结果。提示词的设计上我会明确几件事它的身份、它的输入格式、它的输出格式、以及它的行为边界。比如我会写你是一个信息检索专员你会收到一个 JSON 格式的查询请求包含 query 和 max_results 两个字段。你需要返回一个 JSON 数组每个元素包含 title、content、source 三个字段。如果检索不到相关信息返回空数组不要编造内容。这里的关键是强制结构化输出。我会在提示词里给出明确的 JSON schema并且在代码层面做校验解析失败就重试。实测下来加了 schema 约束之后解析成功率能从百分之七八十提升到百分之九十五以上。工具配置上调研员一般需要一到两个检索工具。我建议一开始只配一个跑通了再加。工具的描述要写得非常清楚包括它接受什么参数、返回什么格式、什么情况下该用、什么情况下不该用。模型选工具主要靠描述描述写得含糊它就会乱选。4.3 定义分析员与审核员调研员跑通之后接下来加分析员。分析员的职责是接收调研员的结构化输出做归纳、对比、提炼产出结论。它的提示词重点是分析框架——你要告诉它从哪些维度去分析否则它容易泛泛而谈。比如我会写你需要从时效性、可靠性、相关性三个维度评估每条信息并给出综合评分。审核员是整个流程的质量守门人。它的职责是检查前面所有环节的产出找出逻辑漏洞、事实错误、格式问题。审核员的提示词要特别强调批判性我会写你的默认立场是怀疑你需要主动寻找问题。如果确实没有问题明确说明审核通过并给出理由。同时审核员的输出也要结构化包含是否通过、问题列表、修改建议三个字段。这三个角色搭起来一个最小的调研→分析→审核流水线就成型了。我建议先把这个最小闭环跑通验证消息传递、状态管理、错误处理都没问题再去加更多角色。一上来就搭七八个智能体出了问题你根本不知道是哪一环的锅。4.4 关键参数的选择与计算多智能体系统里有几个参数直接决定了系统的行为和成本我一个个说。温度temperature不同角色应该用不同的温度。调研员需要一定的发散性来覆盖更多信息温度可以设高一点比如 0.7分析员需要稳定和一致温度设低一点比如 0.3审核员需要严格温度设到 0.1 甚至 0。这个不是拍脑袋而是根据角色的创造性需求来定的——越需要严谨的角色温度越低。最大 token 数这个要根据角色的输出长度来估。调研员的输出可能比较长因为要返回多条信息可以给到 2000审核员的输出通常较短1000 就够了。设置过大浪费成本设置过小会导致输出被截断反而要重试更浪费。超时时间每个智能体的调用都要设超时避免某个环节卡死拖垮全局。我的经验值是单次调用超时设在 30 到 60 秒之间具体看任务复杂度。超时之后要有明确的降级策略比如重试一次再失败就跳过并记录而不是无限等待。重试次数重试不是越多越好。我一般设最多重试 2 次因为如果连续三次都失败大概率不是偶发问题而是提示词或者工具配置有根本性缺陷再重试也是浪费。这时候应该把失败案例记下来人工分析。并发度如果多个子任务互相独立可以并发跑。但并发度不是越高越好要考虑模型接口的速率限制。我一般从并发度 3 开始试观察有没有触发限流再逐步往上调。4.5 完整流程串起来一次任务的完整生命周期把上面这些拼起来一次完整任务的流程是这样的用户提交任务系统生成一个唯一的任务 ID初始化共享状态。调度中心根据任务类型决定第一个执行的是哪个智能体通常是调研员。调研员接收任务调用检索工具产出结构化结果写入共享状态。调度中心检查状态确认调研阶段完成触发分析员。分析员读取调研结果做分析产出结论写入共享状态。调度中心触发审核员审核员检查全链路产出。如果审核通过任务标记完成返回最终结果如果不通过根据问题类型决定是打回给某个环节重做还是直接返回带问题的结果。整个过程中所有消息和状态变更都记录日志方便事后追溯。这个流程看起来简单但每一步都有细节。比如第 7 步的打回逻辑就要小心死循环——如果审核员一直不通过分析员一直重做就会无限循环。我的做法是设置一个最大重做次数比如 3 次超过就直接返回当前结果并标注未通过审核让人工介入。5. 常见问题与排查技巧实录5.1 智能体陷入无限循环怎么办这是多智能体系统里最常见的问题没有之一。表现就是两个智能体来回传递消息谁也说服不了谁或者一个智能体反复调用同一个工具。根本原因通常是缺少明确的终止条件。排查思路是这样的先看日志确认循环发生在哪两个角色之间然后检查它们的提示词里有没有明确的什么情况下停止的指令。很多时候问题就出在提示词只说了要做什么没说什么时候算做完。解决方法有三层。第一层是在提示词里加终止条件比如如果你已经连续两次得到相同结论就停止并输出当前结果。第二层是在调度层加硬性限制比如同一个角色连续被调用超过 3 次就强制中断。第三层是加全局的步数上限整个任务超过 N 步就终止。这三层保险叠起来基本能杜绝无限循环。5.2 消息格式解析失败怎么排查结构化输出虽然好但解析失败也是家常便饭。常见原因有几个模型输出了额外的解释文字、JSON 格式有语法错误、字段名拼写不一致。我的排查流程是先把原始输出打印出来看确认是哪种问题。如果是模型多说了话就在提示词里强调只输出 JSON不要有任何其他文字并且在代码里做容错——用正则把 JSON 部分抠出来再解析。如果是语法错误就加重试机制让模型重新生成。如果是字段名不一致那就要检查提示词里的 schema 定义是不是够清晰必要时给出完整的示例。提示我强烈建议在开发阶段把每次模型调用的原始输入和输出都完整记录下来。排查格式问题时没有原始日志你就是在盲猜。5.3 成本失控的预防与优化多智能体系统跑起来之后成本很容易失控因为调用次数是单智能体的好几倍。我见过一个项目本来预算一个月几百块结果因为循环和重试一周就烧掉了几千。预防成本失控我有几个习惯。第一是开发阶段用便宜的小模型把流程跑通、提示词调好之后再换成大模型做最终验证。第二是给每个任务设 token 预算上限超过就终止避免单个任务无限消耗。第三是定期分析日志找出调用次数异常多的环节针对性优化。第四是缓存重复的调用如果同样的输入反复出现直接返回缓存结果不用重新调模型。优化方面最有效的手段是精简提示词。很多人写提示词喜欢长篇大论其实很多内容是冗余的删掉不影响效果但能省不少 token。另外能不用模型的地方就不用比如一些简单的格式转换、字段提取用代码规则处理比调模型又快又便宜。5.4 常见问题速查表问题现象可能原因排查方向解决手段智能体无限循环缺少终止条件查日志定位循环角色提示词加终止条件调度层限流消息解析失败输出格式不规范打印原始输出强化 schema 约束正则容错重试任务卡死无响应某环节超时未处理查超时日志设超时降级策略成本异常飙升循环或重试过多分析调用日志设预算上限缓存精简提示词输出质量不稳定温度设置不当对比不同温度效果按角色调整温度状态丢失状态未持久化检查存储逻辑引入持久化定期快照5.5 几个文档里不会写的避坑心得最后分享几个我自己踩出来的经验这些在官方文档里基本找不到。第一不要迷信智能体越多越好。我一开始也犯过这个错觉得角色越多系统越强大结果搭了七八个智能体调试成本指数级上升效果还不如三个角色的精简版。后来我总结出一个原则每增加一个角色必须能明确说清楚它解决了什么前一个角色解决不了的问题说不清楚就别加。第二提示词的版本管理很重要。多智能体系统里提示词是核心资产改一个词可能影响全局。我现在的做法是把所有提示词纳入版本控制每次修改都记录改了什么、为什么改、效果如何。这样出问题可以快速回滚也能积累经验。第三先手动跑通再自动化。在写调度代码之前我会先手动扮演各个角色把整个流程走一遍确认逻辑没问题。这一步看起来笨但能省下大量调试代码的时间。很多逻辑漏洞在手动阶段就能发现不用等到代码跑起来才暴露。第四日志要记全但要有结构。日志不是越多越好关键是要能快速检索。我会给每条日志打上任务 ID、角色名、阶段标记这样排查时可以直接按维度过滤不用在几万行日志里大海捞针。第五给系统留人工介入的口子。再好的自动化系统也会遇到搞不定的情况这时候能让人快速接手非常重要。我会在关键节点设置暂停等待人工确认的选项遇到审核不通过或者重试超限时自动暂停并通知而不是硬着头皮往下跑。这套东西我陆陆续续打磨了大半年从最开始的一团乱麻到现在相对稳定中间踩的坑基本都在这了。多智能体协作这个方向技术本身还在快速演进今天好用的方案明天可能就被更好的替代但底层的那些设计原则——职责清晰、通信规范、状态可控、留有余地——是不会过时的。把这几条吃透不管工具怎么变你都能快速搭出靠谱的系统。