agency-agents 这个词最近在 AI 开发者的圈子里越来越火。说白了它就是把多个 AI Agent 组织成一个类似代理公司的结构有负责拆任务、派活的 lead有负责查资料的 researcher有专门写代码的 coder还有做验收的 reviewer。它们围绕同一个目标分工协作而不是各自拿同一个 Prompt 硬怼同一件事。作为一个从单 Agent 一路做到多 Agent 编排、踩了不少坑的开发者这篇就聊聊我在实际项目中搭建 agent agency 的思路、架构、代码落地和避坑经验。如果你正在做 RAG 应用、自动化流程、复杂代码生成这类任务这篇文章应该能帮你少走一段弯路。1. 为什么单 Agent 搞不定非要组织一个 agency1.1 单 Agent 的三个典型瓶颈先说第一个上下文窗口。现在主流模型的上下文从 128K 到 1M 都有了听起来很大但真实跑复杂任务时根本不够用。比如让它调研某个行业再生成一份带数据、带图表、带可运行代码的报告它得先读资料、再写分析、再调代码、最后排版。每一步都要把之前的信息塞进上下文里塞到最后前面读的资料可能已经被截断或者互相覆盖模型开始失忆。我在项目里见过最典型的现象就是一个 Agent 写报告写到第三章突然忘了第一章定下的数据口径前后数字对不上而你还很难在最终输出里一眼发现这个问题。第二个瓶颈是长任务能力衰减。同一个模型在对话开头表现得像资深专家到第 30 轮之后就开始重复输出、逻辑混乱、答非所问。这不是玄学是模型在超长上下文里的注意力分布越来越散跟人类长时间集中注意力之后会疲劳是一个道理。你用一个人海战术式的超长 Prompt 硬撑最后只是在赌模型的输出稳定性。第三个瓶颈是角色串味。搜索、代码、写作、校验全塞给同一个 Agent它的 system prompt 会变成一个四不像既要谨慎核实数据又要大胆发散创意还要严格审查自己的输出。这种既当运动员又当裁判的设定模型很难同时演好。我在实践里发现同一个模型用不同的专用角色 prompt产出的质量往往比一个全能 prompt高出不少哪怕模型本身没换。1.2 Agency 模式的本质把复杂度分摊agency 的思路就是效仿真实公司里的分工不指望一个人全能而是让每个 Agent 只干一类活干到极致。Lead 负责把用户的大目标拆成子任务分给对应的 specialist最后再由 reviewer 统一把关。这个模式带来的三个直接好处。第一每个 Agent 的 system prompt 可以写得很纯粹比如 researcher 就专心搜索和核实不需要关心输出排版coder 就专心写可验证的代码不需要考虑措辞风格。prompt 越纯行为就越可控。第二子任务可以并行执行比如报告里的三个章节分开调研比一个 Agent 串行跑要快得多省下的不只是时间还有整体上下文占用。第三引入独立的 reviewer 环节等于给输出加了一道质量闸门你可以在这一步做格式校验、数据一致性检查、代码可执行性验证而这些如果放在同一个 Agent 的上下文里几乎很难干净地完成。用一句话总结agency-agents 解决的问题不是让模型变得更聪明而是通过工程手段把一份超出单 Agent 能力范围的复杂任务切分到多 Agent 协作的舒适区里。2. 架构拆解一个可落地的 agent agency 由哪几块组成2.1 角色层Lead 与 Specialist 怎么划分角色划分是整个 agency 架构里最关键的一步也是最容易被做坏的一步。我见过两种极端一种是把所有职责堆到一个超级 Agent里这等于没拆另一种是拆了十几个细碎角色结果光协调它们就要花掉大半 token。我的经验是两条原则。第一只要两个职责的输出形态有明显差异就应该拆开。researcher 的产出是结构化的资料笔记coder 的产出是代码和运行结果writer 的产出是连贯的文章段落这些形态差异本身就决定了它们需要不同的工具和不同的校验标准。第二角色数量控制在 4 到 6 个以内。角色太少单个 Agent 会重新背上多种职责角色太多lead 的调度压力、token 开销和失败概率都会指数上涨。对一个典型的内容生产型任务researcher、coder、writer 加一个 reviewer配合 lead 做总控已经能覆盖九成场景。lead 这个角色要刻意做得薄。它不负责具体执行只负责拆解、调度和整合。它的 system prompt 里要明确写清楚不要自己下场做搜索和编码。否则它会仗着自己是 lead 疯狂调用工具把调度逻辑和具体执行混在一起最后整个流程变成一团看不清的毛线。2.2 通信层共享状态、消息队列、还是直接函数调用多 Agent 之间怎么说话是架构里第二个决定成败的点。常见做法有三种共享状态、消息传递、直接函数调用。共享状态所有 Agent 共用一个结构化的内存对象比如一个 JSONLead 把全局计划、阶段性结论、约束条件写到里面各 specialist 只读取和自己相关的部分再把结果写回去。消息传递每个 Agent 维护一个消息列表像聊天一样把消息发来发去。直接函数调用Agent A 在处理过程中直接调用 Agent B 的入口函数拿到返回结果继续干。我强烈建议优先用共享状态原因很简单LLM 的上下文是只追加的如果你每次都把整个聊天历史传给下一个人token 消耗会爆炸式增长。共享状态允许你只把一个紧凑的当前快照推给某个 Agent它看到的是任务经过压缩后的核心事实而不是几十轮的喋喋不休。打个比方一个项目团队不会让每个新成员都去翻全部的聊天记录而是看一张任务看板、一份现状文档和一个下一阶段目标。共享状态就是这个任务看板。我在实现里通常维护几个固定字段plan存拆解后的子任务列表facts存各角色沉淀下来的、经过核实的结论artifacts存代码和文件产出review_notes存 reviewer 的检查意见。2.3 工具层每个 Agent 的合法工具范围工具权限是 agency 架构里最容易被忽略、出事之后最难受的部分。每个 Agent 的 tools 列表必须是它自己职责相关的子集而不是全家桶。比如 researcher 可以拿到 web_search、url_fetch、arxiv 搜索这类检索工具coder 可以拿到 code_exec、file_write、dependency 安装工具writer 只拿到文本处理工具不能执行任意代码。这样做的第一个理由是安全如果某个 Agent 被外部内容诱导prompt injection 是真实存在的它手里没有破坏性工具影响面就小得多。第二个理由是效率工具列表越短模型在选择工具时的困惑越小调用错误率越低。另外一个容易被忽略的点是工具输出的截断。搜索返回的网页、代码执行产生的日志都可能非常长如果不做长度上限这些内容会直接灌进 specialist 的上下文既贵又乱。我在封装工具时都会给返回内容设置一个硬上限比如搜索摘要最多返回 2000 字代码执行 stdout 最多返回 4000 字符超出部分用内容过长已截断关键信息为……这种格式收尾。2.4 控制层任务分解、调度、重试和终止控制层负责在所有 Agent 之上建立明确的运行规则这一层的原则是能用代码做的判断就不要让模型去做。任务分解要建立固定格式。Lead 的输出不能是一段自由文本而应该是一个 JSON 数组每个元素包含task_id、agent负责的角色、instruction对 specialist 的明确指令、dependencies依赖哪些前置任务的产出。有了这个格式代码才能可靠地把任务分发给对应角色而不是靠正则去猜。调度方面没有依赖关系的子任务应该并行执行有依赖的按拓扑顺序来。最简单的方式是用线程池处理一批独立任务然后统一收集结果。重试策略也要定死某个 specialist 调用失败最多重试 2 到 3 次每次换一个更精简的指令超过次数就放弃该子任务把该子任务执行失败写进结果而不是让整个流程无限卡住。终止条件是最容易被忽视的。我在实践中会设置三层保护最大轮次max_rounds比如 5 轮、总 token 预算比如 80 万 token超出强制停止、以及 reviewer 的验收结果通过即结束。没有这些硬限制你在半夜会看到一个 agency 在死循环里白白烧钱。3. 实操搭一个最小可用的 agent agency3.1 技术选型框架对比与我的选择现在市面上的多 Agent 编排框架不少我在选型上做过一组对比方案编排方式适合场景上手成本最需要注意的坑LangGraph有向图 共享状态流程固定、分支明确的复杂任务中等状态 Schema 要提前设计否则后期改造成本高CrewAI角色/任务声明式快速搭建原型、验证角色分工低复杂校验逻辑容易被塞进 prompt难以调试AutoGen对话式多 Agent开放式讨论、头脑风暴型任务中等对话轮次不可控token 消耗容易失控自研编排直接代码控制需要深度定制、严格的成本/安全控制高灵活但所有坑都要自己踩一遍我给自己的建议分两档如果是验证想法、快速出 Demo用 CrewAI 这类声明式框架最省事几个角色、几个任务写清楚就能跑起来如果是做长期维护的生产级系统我倾向于自研一套轻量编排或者用 LangGraph 这类把状态控制暴露得很清晰的框架。原因很简单production 场景下你不仅要管Agent 能不能跑通还要管跑通了之后 token 花在哪、失败在哪一步、能不能单独重试某一步这些在声明式框架里往往很难插手。3.2 定义角色和工具一旦确定了架构和框架第一步是把角色落成代码。以下是我常用的最小结构不依赖任何特定框架只依赖最基础的 Python 数据类# agents.py from dataclasses import dataclass, field dataclass class Agent: name: str role: str tools: list[str] model: str gpt-4o-mini temperature: float 0.2 def run(self, instruction: str, shared_state: dict) - str: # 组装 system prompt instruction 所需 reference然后调用 LLM ...对应的角色定义长这样LEAD Agent( namelead, role任务总控与整合, tools[task_decomposer], temperature0.1, ) RESEARCHER Agent( nameresearcher, role信息检索与事实核查, tools[web_search, url_fetch], temperature0.2, ) CODER Agent( namecoder, role编写并验证可运行代码, tools[code_exec, file_write], temperature0.1, ) WRITER Agent( namewriter, role基于 facts 与 artifacts 撰写最终文章, tools[text_formatter], temperature0.3, ) REVIEWER Agent( namereviewer, role质量验收检查数据一致性、格式规范与可复现性, tools[checker], temperature0.0, )这里有几个细节值得注意。第一temperature 的设置是有意的lead、coder、reviewer 偏向确定性工作温度要低writer 需要一点语言组织的随机性温度可以略高。第二每个 Agent 的 tools 都是够用就好这是前面说的最小权限原则。第三run方法内部要做一个统一入口从共享状态里提取这个 Agent 需要的字段而不是把整个 state 都塞给它。3.3 编排主循环核心编排逻辑其实不长复杂度主要藏在上面的数据结构和异常处理里。一个最小闭环可以长这样# orchestrator.py def run_agency(task: str, shared_state: dict) - dict: # step 1: lead 拆解任务 shared_state[plan] LEAD.run( f将以下目标拆解为可并行执行的子任务输出 JSON 列表: {task} ) # step 2: 并行执行无依赖子任务 results {} for sub in shared_state[plan]: agent agents_registry[sub[agent]] results[sub[task_id]] agent.run(sub[instruction], shared_state) # step 3: 汇总中间产物 shared_state[facts] collect_facts(results) shared_state[artifacts] collect_artifacts(results) # step 4: writer 生成初稿 shared_state[draft] WRITER.run( 基于 facts 与 artifacts 撰写完整交付物, shared_state ) # step 5: reviewer 验收不合格则 lead 修稿 for _ in range(MAX_RETRY): review REVIEWER.run(shared_state[draft], shared_state) if review[passed]: break shared_state[draft] LEAD.run( f根据以下意见修改稿件: {review[comments]}, shared_state ) return shared_state[draft]这个循环最核心的工程点在 step 2 的并行和 step 5 的验收。并行这一块我实际用的是ThreadPoolExecutor去跑多个子任务每个子任务内部再去调 LLM整体耗时从串行的十几分钟压缩到两三分钟。验收这一块reviewer 不能只问这个输出好不好而是必须拿着明确的 checklist 判断比如所有引用的年份是否一致代码块是否包含完整 import文件路径是否真实存在。为了稳定我还会把一部分校验写成硬代码比如用正则检查日期一致性用代码执行来验证代码块能不能跑这些不依赖模型的临场发挥。3.4 实测效果一个多步骤任务从头跑到尾拿我之前做过的一个试点任务来说明让系统产出某城市夜间经济发展分析报告要求包含至少 5 组数据、1 段 Python 绘图代码和完整分析文本。这个任务如果交给单 Agent它会自己搜索、自己写代码、自己写文章最后交上来的东西可能看起来不错但数据口径混乱、代码运行报错、章节之间逻辑断裂。换成 agency 架构之后lead 把这个任务拆成了三块researcher 负责收集夜间经济相关数据和来源coder 负责把数据可视化代码跑通并截图writer 负责整合分析文本。最后 reviewer 在验收时抓到了一个问题——researcher 引用的数据有 2023 年的也有 2024 年的而正文里没有说清楚口径于是 lead 根据 reviewer 的意见把稿件打回去要求统一标注数据年份最终输出才过关。这个例子想说明的是agency 不会让模型突然变得很懂夜间经济它只是把搜得准、写得稳、查得严这三件事分散到不同 Agent 身上每一件都变得更简单、更可控。单 Agent 的失败是模糊的——你很难定位是搜索出了问题还是写作出了问题agency 的失败是清晰的——你一眼就能看到是 researcher 给的 facts 不够还是 reviewer 的标准太松。4. 踩坑记录agency 架构里最常见的翻车点4.1 上下文污染Lead 成了复读机我踩的第一个大坑是 lead 在整合结果时把各 specialist 的完整输出全塞进自己的上下文然后它开始逐字复述这些输出而不是整合。后来我发现问题出在 specialist 的返回结果里混入了大量与任务无关的过程日志比如我正在搜索请稍等我找到了 10 个结果这类废话。解决办法有两层。第一层在 specialist 的 prompt 里明确要求只输出最终结果不要输出中间过程并且规定输出格式是紧凑的 Markdown 列表。第二层在代码里对 specialist 的原始输出做一次清洗和压缩提取关键字段后再写入共享状态。这就像是给项目团队加了一个理念每个人在任务看板上只更新结论不刷屏过程日志。4.2 token 黑洞和死循环token 消耗失控是 agency 架构最大的隐性杀手。我见过一个の任务看起来很简单但因为有多个 Agent 之间反复确认、互相补充信息最后实际 token 消耗超过了预估的 10 倍。加上没有终止条件整个流程在一个lead 让 researcher 补充数据 → researcher 给出更多来源 → lead 觉得还不够 → 继续让 researcher 补充的循环里越陷越深。解决方式前面也提到了就是硬性保护总 token 预算、最大轮次上限、超时强制中止。我还加了一条规则lead 每次要求补充信息之前必须在共享状态里明确写出这次补充具体要回答哪个问题、用于哪个章节如果没有这个字段代码直接拦截不允许发起新一轮调用。这等于强制让调度决策变得可审计。4.3 reviewer 形同虚设另一个让我头疼的问题是 reviewer 这个角色经常放水。早期版本的 reviewer prompt 写的是请审查以下输出是否有问题结果它几乎永远回答没有明显问题。后来我意识到这种开放式乐观评价是模型在低温度和高模糊度下的常见表现。必须把 reviewer 变成分部检查机器给它一个逐项打分的 checklist每一项要么通过要么给出具体修改建议并且要求格式是结构化 JSON。比如对一份报告checklist 至少包括所有数据是否标注来源与年份章节标题是否与 lead 的 plan 一一对应代码块是否能独立运行正文是否存在互相矛盾的数字。如果 reviewer 在某个登记了数据来源缺失它必须列出具体是哪一段缺了来源。这样的 reviewer 才是真正有价值的独立质检员。4.4 排查速查表把几个高频问题整理成一张表方便你遇到类似症状时直接对照现象可能原因排查方法常用解法Lead 输出重复、遗忘原任务上下文被过程日志塞满打印调用时的输入 token 数对子任务结果做压缩后再写入共享状态任务迟迟不结束没有终止条件或 Agent 自行加戏查看运行日志中的循环次数设置 max_rounds、token 预算、超时中止token 消耗远超预估每次调用都传递完整历史统计每个 Agent 的输入 token 占比用共享状态快照替代完整历史只传必要字段reviewer 从不过问任何问题检查标准太模糊、温度偏高看 review 返回 JSON 的字段分布改成逐项 checklist 结构化 JSON 输出子任务之间数据口径矛盾specialist 看不到全局约束检查 plan 阶段是否写入了全局 summary在共享状态里维护 facts 字段lead 每次派活前先同步5. 什么时候真不该用 agency-agents说实话agency 架构不是银弹很多时候它是过度设计。我在三个场景里明确劝退第一简单问答和常规 RAG 任务。如果你的需求是根据文档回答一个问题单 Agent 加上好的检索工具已经绰绰有余硬拆成多 Agent 只会让延迟从 2 秒变成 20 秒还多了好几个失败点。第二对延迟极度敏感的场景。一次多 Agent 协作通常意味着至少 3 到 5 轮模型调用每轮 1 到 3 秒延迟加起来就是几十秒甚至分钟级。这在交互式体验里不可接受。第三团队没有精力维护编排逻辑。agency 架构引入的新失败面不在模型而在编排共享状态设计、重试策略、工具权限、成本监控这些都是长期工程责任。如果只是临时跑一次任务直接把任务塞给单 Agent 加上一份详细 Prompt反而更稳。判断标准其实很简单先让单 Agent 去跑你的任务如果它跑得动哪怕结果粗糙点也别上 agency只有当你明确了单 Agent 究竟卡在哪一个环节、而这个环节可以被独立拆分和优化时才值得动手搭这套系统。我见过太多人为了用上多 Agent而强行拆任务最后换来一堆没必要的编排故障。最后分享一个我自己的体会从单 Agent 迁移到 agency 架构我前后重构了快两个月最深的感受是它本质上是对工程质量的要求而不是对模型能力的要求。角色边界、状态管理、错误处理、成本控制每一环都得按工程标准来写。如果你正准备动手我的建议是先挑一个真正让单 Agent 吃力的真实任务跑通最小闭环再逐步加角色、加并行、加验收。设计 agent agency 最大的坑不是模型不够聪明而是你的编排逻辑还没有清晰到能被代码表达出来。