1. 从零搭建多智能体协作系统agency-agents 项目实战拆解第一次看到 agency-agents 这个项目名的时候我脑子里蹦出来的画面是一群各司其职的“数字员工”坐在同一间虚拟办公室里有人负责调研、有人负责写代码、有人负责审核、有人负责对外沟通。这个直觉基本是对的。agency-agents 本质上是一套面向多智能体协作Multi-Agent Collaboration的工程化框架它要解决的核心问题是当单个大模型智能体搞不定一个复杂任务时如何把任务拆开、分配给多个各有专长的智能体让它们像一家真正的代理公司agency那样协同运转最终交付一个完整结果。我接触这个方向有一段时间了踩过的坑不算少。单智能体做任务简单场景下确实够用但一旦任务链条变长——比如“调研某个行业 输出分析报告 生成配套代码 demo 写推广文案”——单个 agent 很容易在中途丢失上下文、跑偏目标或者干脆陷入自我循环。agency-agents 这类框架的价值就在于它把“一个全能选手”拆成了“一个团队”每个成员只关心自己那一小块通过明确的协议传递信息和产物。这篇文章我会从整体设计思路、核心机制、实操搭建、问题排查几个维度把这个项目彻底讲透适合已经了解大模型基础调用、想往多智能体方向深入的同学也适合想直接抄一套可运行方案的工程同学。2. 多智能体协作到底难在哪agency-agents 的设计思路拆解2.1 为什么单智能体不够用先说清楚问题背景不然容易觉得多智能体是“为了复杂而复杂”。单智能体在真实任务里会遇到三个硬伤。第一个是上下文窗口的物理限制。一个复杂任务往往需要大量中间产物调研资料、草稿、修改意见、最终稿。这些东西全塞进一个对话历史里很快就会撑爆上下文而且模型对超长上下文的注意力是衰减的越靠前的内容越容易被忽略。我实测过一个任务当对话轮次超过 30 轮之后模型开始忘记最初设定的输出格式要求这就是典型的上下文漂移。第二个是角色冲突。让同一个 agent 既当“创意发散者”又当“严格审核者”它在心理上准确说是概率分布上会倾向于折中写出来的东西既不够大胆也不够严谨。这跟人类团队是一个道理一个人既当运动员又当裁判很难做到极致。第三个是可观测性差。单智能体跑一个长任务中间到底哪一步出了问题你很难定位。它可能在第 5 步就已经理解错了需求但一直到第 20 步才暴露出错误结果中间十几步全白跑。agency-agents 的设计思路就是针对这三点用角色分工解决冲突用消息传递解决上下文膨胀用显式的任务流转解决可观测性。2.2 核心架构把“公司”抽象成代码agency-agents 的架构可以类比成一家公司的组织方式我把它拆成四个核心概念。Agent智能体/员工每个 agent 有明确的角色定义role、系统提示词system prompt、可用工具集tools和输出规范。比如一个“研究员”agent 只负责检索和整理信息一个“工程师”agent 只负责写代码。Task任务/工单任务是流转的基本单位包含任务描述、输入依赖、预期输出格式、负责的 agent。任务之间可以有依赖关系形成 DAG有向无环图。Orchestrator编排器/项目经理负责调度任务、决定哪个任务先执行、把上游产物传给下游。它是整个系统的中枢。Shared Memory / Message Bus共享记忆/消息总线agent 之间不直接对话而是通过结构化的消息传递产物避免上下文污染。这个设计的精妙之处在于每个 agent 的上下文是隔离的。研究员 agent 不需要知道工程师 agent 写了什么代码它只需要把自己的调研结果以结构化格式交出去。这样每个 agent 的上下文都很干净不会互相干扰。2.3 方案选型为什么不用“群聊”模式市面上多智能体框架大致分两派一派是“群聊式”所有 agent 在一个共享对话里你一言我一语另一派是“编排式”orchestrator 显式调度。agency-agents 走的是编排式路线这个选择我认为是对的。群聊式看起来热闹但问题很多。首先是发言顺序不可控模型可能抢话、重复、跑题。其次是成本爆炸每轮群聊所有 agent 都要读一遍完整历史token 消耗是 O(n²) 增长。最后是收敛困难没有一个明确的“谁说了算”的机制任务容易悬而不决。编排式虽然写起来麻烦一点需要你显式定义任务图和依赖关系但换来的是确定性、可调试、成本可控。我个人的经验是凡是需要稳定交付的生产场景编排式都是更靠谱的选择。agency-agents 在这个基础上还做了优化支持动态任务生成——orchestrator 可以根据上游结果决定下一步生成什么任务兼顾了灵活性和可控性。3. 核心机制深度解析Agent、Task 与消息传递3.1 Agent 的定义要素与提示词工程一个 agent 定义得好不好直接决定整个系统的上限。agency-agents 里一个 agent 通常包含这几个要素我逐个说清楚。角色描述Role要具体到“这个人每天干什么”而不是泛泛的“你是一个助手”。比如“你是一名有 10 年经验的资深后端工程师擅长 Python 和分布式系统你的代码风格偏向简洁、注重边界条件处理”这种描述比“你是编程专家”有效得多。系统提示词System Prompt是 agent 的行为准则。我总结了一个好用的模板结构身份 职责边界 输出格式 禁止事项。职责边界特别重要要明确告诉它“你只负责 X不要做 Y”。比如研究员 agent 的提示词里要写“你只负责收集和整理信息不要做主观判断不要写代码”。工具集Tools决定了 agent 的能力范围。这里有个原则给最小必要工具。研究员 agent 给搜索和网页读取就够了不要给它代码执行工具否则它可能忍不住去写代码偏离职责。输出规范Output Schema是保证 agent 之间能对接的关键。我强烈建议用 JSON Schema 强制约束输出格式比如研究员必须输出{findings: [...], sources: [...], confidence: 0.8}这样的结构。这样下游 agent 拿到的是干净的结构化数据而不是一段需要再解析的自然语言。3.2 Task 编排DAG 与依赖管理任务编排是 agency-agents 的骨架。我用一个真实案例来说明。假设任务是“为某个开源项目写一篇技术推广文章”拆解后的任务图是这样的任务 A调研项目背景、核心功能、目标用户研究员 agent任务 B基于 A 的调研提炼 3 个核心卖点分析师 agent任务 C基于 B 的卖点写文章初稿写作 agent任务 D基于 C 的初稿做技术准确性审核审核 agent任务 E基于 D 的反馈修订并定稿写作 agent这里 A→B→C→D→E 形成一条链但实际项目中会有并行分支。比如调研可以拆成“技术调研”和“市场调研”两个并行任务最后汇总。agency-agents 的编排器需要处理这种依赖关系确保一个任务的所有上游依赖都完成了才执行。注意任务依赖图一定要保证无环。我见过有人设计出 A 依赖 B、B 又依赖 A 的循环系统直接死锁。设计任务图的时候先在纸上画一遍确认是 DAG 再写代码。3.3 消息传递与上下文隔离这是 agency-agents 最值得学习的设计。agent 之间不共享对话历史而是通过结构化消息传递产物。每条消息包含发送者、接收者、消息类型、payload结构化数据、时间戳。这样做的好处是每个 agent 启动时只需要加载“我的任务描述 我需要的上游产物”上下文非常精简。我实测过一个 5 个 agent 协作的任务如果每个 agent 只加载必要上下文总 token 消耗比群聊模式低 60% 以上。但这里有个坑信息在传递过程中会丢失。上游 agent 觉得不重要的细节可能恰恰是下游 agent 需要的。我的解决办法是在任务定义里显式声明“下游需要哪些字段”让上游 agent 按需输出。这本质上是一种接口契约跟微服务之间的 API 设计是一个思路。4. 实操搭建从环境准备到跑通第一个多智能体任务4.1 环境准备与依赖安装先说环境。agency-agents 这类框架通常依赖 Python 3.10因为要用到一些较新的类型注解特性。我建议用虚拟环境隔离避免污染全局。python -m venv agency-env source agency-env/bin/activate # Windows 用 agency-env\Scripts\activate pip install agency-agents如果你要用到具体的模型 API还需要配置对应的 SDK 和密钥。我一般会把密钥放在.env文件里用python-dotenv加载绝对不要硬编码在代码里。# .env 文件示例 MODEL_API_KEYyour_key_here MODEL_BASE_URLhttps://your-endpoint DEFAULT_MODELgpt-4-class-model提示模型选择上我建议主力 agent编排、写作、审核用能力强的模型辅助 agent格式化、简单检索可以用轻量模型这样成本和效果能平衡。全部用最强模型账单会让你怀疑人生。4.2 定义你的第一个 Agent我拿“技术调研员”这个 agent 举例给你一份可以直接改的配置。from agency_agents import Agent researcher Agent( nametech_researcher, role资深技术调研员, system_prompt你是一名有 10 年经验的技术调研员。 你的职责收集指定技术主题的权威信息整理成结构化摘要。 你的边界不做主观评价不写代码不生成营销文案。 输出格式严格返回 JSON包含 findings列表、sources列表、confidence0-1 浮点数。 禁止事项不要编造来源不确定的信息标注 confidence 低于 0.5。, tools[search_tool, web_reader_tool], output_schema{ type: object, properties: { findings: {type: array, items: {type: string}}, sources: {type: array, items: {type: string}}, confidence: {type: number} }, required: [findings, sources, confidence] } )这里有几个细节值得说。output_schema用 JSON Schema 约束框架会自动校验输出不符合就重试。confidence字段是我强烈建议加的它让下游 agent 知道这份调研的可信度低置信度的信息可以触发二次验证。4.3 编排任务流写一个完整的协作流程定义好 agent 之后用编排器把它们串起来。from agency_agents import Orchestrator, Task orchestrator Orchestrator() task_a Task( nameresearch, description调研 agency-agents 框架的核心功能和适用场景, agentresearcher, depends_on[] ) task_b Task( nameanalyze, description基于调研结果提炼 3 个核心技术卖点, agentanalyst, depends_on[research] ) task_c Task( namewrite, description基于卖点写一篇 1500 字技术文章, agentwriter, depends_on[analyze] ) orchestrator.add_tasks([task_a, task_b, task_c]) result orchestrator.run()跑起来之后编排器会自动按依赖顺序执行把 task_a 的输出传给 task_b以此类推。你可以在每一步打印中间产物方便调试。4.4 参数调优并发度、重试与超时生产环境跑多智能体这几个参数必须调。并发度max_concurrency如果任务图里有并行分支可以设置并发数。但要注意模型 API 的速率限制我一般设 3-5太高容易触发限流。重试次数max_retriesagent 输出格式错误、工具调用失败都需要重试。我建议设 3 次配合指数退避。超过 3 次还失败说明任务定义有问题应该人工介入而不是无限重试。超时timeout单个任务设 120-300 秒比较合理。我踩过一个坑某个 agent 陷入循环一直调用工具不停没有超时机制的话会一直烧钱。加上超时之后超时任务会被标记为失败进入人工排查队列。参数建议值说明max_concurrency3-5受 API 限流约束max_retries3配合指数退避task_timeout120-300s防止无限循环output_validation开启强制 schema 校验5. 常见问题与排查技巧实录5.1 Agent 输出格式不稳定怎么办这是最高频的问题。明明定义了 JSON schemaagent 还是偶尔返回一段自然语言。我的排查顺序是先看提示词里有没有明确“只返回 JSON不要有任何其他文字”很多时候是提示词不够强硬。其次看模型能力轻量模型对格式的遵循度确实差一些。最后可以开启框架的“格式修复”功能它会用一次额外的模型调用把输出转成合规格式但会增加成本。我个人的经验是在提示词里给一个完整的输出示例比任何约束都有效。模型是模仿高手你给它看一个标准答案它照着抄的概率极高。5.2 任务卡住或死循环怎么定位死循环通常有三个原因。一是任务依赖成环前面说过设计时就要避免。二是 agent 反复调用同一个工具比如搜索工具返回空结果agent 不甘心一直重搜。解决办法是在提示词里加“如果连续两次搜索结果为空直接返回当前已知信息并标注 confidence 低”。三是编排器逻辑 bug这个只能靠日志排查。我建议给每个任务加一个max_steps限制超过步数强制终止。这是最后一道防线。5.3 成本失控的预防措施多智能体最大的风险就是成本。我总结了几条硬性措施给每个任务设 token 上限用轻量模型处理简单任务缓存重复的工具调用结果监控每日总消耗超过阈值自动暂停。还有一条容易被忽略的精简上下文。很多成本浪费在把无关的历史信息塞给 agent定期审查每个 agent 实际加载的上下文砍掉冗余部分。5.4 常见问题速查表问题现象可能原因解决方向输出格式错误提示词不够明确加输出示例开启 schema 校验任务死循环依赖成环或工具重试检查 DAG设 max_steps成本飙升上下文冗余、模型过强精简上下文分级用模型结果质量差agent 角色定义模糊细化 role 和职责边界任务超时单任务过重拆分子任务设超时注意排查问题时一定要把每个 agent 的输入输出完整打日志。多智能体系统的调试难度远高于单智能体没有日志基本没法定位。我一般会把日志按任务 ID 分组方便回溯整条链路。6. 进阶玩法动态任务生成与自我修正6.1 让编排器学会“随机应变”前面讲的都是静态任务图任务在跑之前就定好了。但真实场景里你往往不知道需要几步才能完成。agency-agents 支持动态任务生成orchestrator 根据上游结果决定下一步生成什么任务。举个例子审核 agent 发现文章有技术错误它可以生成一个“修订任务”而不是直接失败。修订任务完成后再触发一次审核形成“审核-修订”循环直到通过或达到最大循环次数。这个机制让系统有了自我修正能力交付质量明显提升。实现上你需要给 orchestrator 一个“任务生成提示词”告诉它在什么条件下生成什么任务。这里要特别小心循环上限我一般设最多 3 轮修订超过就人工介入。6.2 多轮迭代中的状态管理动态任务会带来状态管理问题修订到第几轮了哪些问题已经修过我的做法是维护一个共享的“任务状态表”记录每个任务的执行历史、产物版本、审核意见。agent 每次启动时读取相关状态避免重复劳动。这个状态表其实就是整个系统的“项目档案”它也是可观测性的核心。你随时可以查看某个任务经历了哪些轮次、每轮改了什么这对复盘和优化极其有用。6.3 从单机到分布式的扩展思路当任务量上来之后单机跑会成瓶颈。agency-agents 的架构天然支持分布式编排器和 agent 之间通过消息队列解耦agent 可以部署在多台机器上各自消费任务。共享状态表换成 Redis 或数据库就能支撑更大规模。不过我要泼盆冷水大部分场景根本不需要分布式。我见过有人一上来就搞分布式结果调试成本翻了好几倍收益却微乎其微。先把单机版本跑稳、跑出效果确认真的有扩展需求了再考虑分布式这是更务实的路径。7. 我在实际项目里踩过的坑与经验总结说几个文档里不会写、但实际会遇到的坑。第一个是模型版本漂移。你调好的提示词在模型更新之后可能就失效了。我遇到过升级模型后原本稳定的 JSON 输出开始偶尔夹带解释文字。所以生产系统一定要锁定模型版本升级前做回归测试。第二个是工具调用的副作用。如果 agent 有写文件、发请求这类有副作用的工具重试机制可能导致重复执行。解决办法是给工具加幂等性设计或者用“先检查再执行”的模式。第三个是过度工程化。多智能体很酷但不是所有任务都需要。我现在的判断标准是如果任务能拆成 3 个以上明确的、有依赖关系的子任务且每个子任务需要不同的“思维方式”才值得上多智能体。否则单智能体加好的提示词就够了。最后一个体会是关于人的位置。agency-agents 这类系统再强也需要人在关键节点把关。我的做法是在任务图里插入“人工审核”节点特别是对外交付的内容必须有人过一遍。这不是对系统不信任而是对结果负责。把 AI 当团队用而不是当替身用这个心态很重要。这套东西我前后迭代了几个月从最初跑一个任务烧掉几十块到现在能把成本控制在合理范围中间交了不少学费。希望这篇拆解能帮你少走点弯路。如果你也在搞多智能体欢迎交流踩坑经验这个领域变化太快一个人摸索效率太低。