多智能体框架agency-agents：架构设计与稳定性治理-北京尧图网络

“agency-agents”这个项目名字我第一次看到的时候还愣了一下以为是打错了。后来跟作者聊完才发现这名字起得很贴切——它不是一个普通的多智能体框架而是一个专门用来“管理其他代理”的代理。简单说它就是AI智能体团队里的那个“Team Lead”。这阵子我一直在搞多智能体协作试过直接让几个大模型互相传话、试过把工具全塞给一个超级智能体效果都不理想。直到我照着 agency-agents 的思路重新搭了一套带管理层级的代理系统才感觉复杂任务终于能稳稳落地产出了。今天这篇文章就把这个项目内部的架构设计、任务编排机制、稳定性治理以及我在真实环境里调试时踩过的坑一次性讲透。1. 为什么单代理撑不起真实业务三个“必然崩”的场景很多同学一开始都会想现在的模型能力这么强把工具全挂上去一个代理干到底不就行了我一开始也是这么干的直到在下面三个场景里连续翻了车才意识到单代理模式的天花板比想象中低得多。1.1 跨系统数据流转任务做到一半方向就跑偏第一个让我崩溃的场景是跨系统数据流转。任务是从数据库拉昨天的新增用户调用第三方接口做用户分层然后用邮件发送一份分析报告最后把报告归档到云存储。单智能体在执行过程中最大的问题是它容易“失焦”。一开始它还在老老实实查SQL查完统计数据之后可能是上下文太长了也可能被中间某个报错带偏了它居然开始自己编造分层逻辑甚至把还没生成的报告提前“完成”了。你回头看日志每一步看起来都像模像样但最终产物根本不能用。根子在于单代理没有任何机制保证“前一步的产出能可靠地成为后一步的输入”。它更像一个即兴发挥的实习生而不是一个按流程走的手艺人。1.2 多源信息交叉验证一个代理根本忙不过来第二个场景是信息交叉验证。比如你要写一份市场分析需要同时参考行业报告、产品文档、用户反馈还要结合实时的业务数据。这类任务的核心不是“能不能生成”而是“来源是否可靠、结论是否经过多角度校验”。单代理做这件事的时候会出现一个很微妙的问题它会倾向于“自洽”。也就是一旦它脑子里形成了一个初步结论后面阅读材料时就会不自觉地寻找支持这个结论的证据忽略反例。这几乎是所有大模型都有的毛病。要解决它必须让“提出观点”和“检查观点”这两件事由不同角色的代理来干互相形成制衡。1.3 需要人工审批和交互的流程单代理无法表达“卡在哪儿了”第三个场景是有外部依赖的流程。比如报销审批、内容发布审核、代码合并请求这类任务需要停下来等某个人的操作。单代理的状态管理通常是一塌糊涂的——它要么直接超时自杀要么反复重试确定不了的事情把API调用额度烧得一干二净。我当时需要的是一种显式的状态流转哪个子任务依赖外部输入、已经等了多久、下一步可能的选项是什么。这些信息如果不能被结构化地表达和查询整个流程就是黑盒出了问题根本无从下手。1.4 单代理崩溃的三大根因与代理管理层级的必要性总结下来单代理模式崩掉的原因可以归结为三点根因表现后果上下文失焦长任务执行一半偏离原始目标产出不可用步骤不可回滚某一步出错后无法恢复整链失败工具调用缺乏治理无约束地调用API、重复调用成本失控、接口被限流所以要解决这些问题不能靠把单代理调得更聪明而是要引入一层“管理者”。这正是 agency-agents 的核心思路不再让一个代理单打独斗而是像组建小团队一样由一个主代理负责任务分解和进度推进其他专业代理各自负责具体的执行动作。2. 总架构拆解把代理拆成规划器、执行器、验证器三层说清楚了为什么需要代理管理层级接下来就看 agency-agents 内部是怎么落的。它没有搞那种玄乎的“通用智能体协议”而是把体系结构做成了非常务实的三层规划器Planner、执行器Executor、验证器Verifier。2.1 为什么不用“代理间自由对话”而用三层职责分离起初我看设计文档时有个疑问多个代理之间直接发消息是不是就够了像聊天一样代理A问代理B要数据代理B再问代理C要工具权限这不也能跑通吗作者解释了一句话让我印象很深“自由对话式协作的本质是让复杂系统退化成了概率系统。”每个代理都只看到局部信息做出的决定是概率性的消息传来传去整体行为完全不可预测。而三层职责分离本质是建立一个类似于“前后端分离”的开发范式——规划器控制流执行器负责逻辑验证器把关质量。每一层只干自己那一摊事接口明确出问题了也知道该查谁。2.2 代理注册表一个基础设施级的组件在这个框架里有一个容易被忽视但非常关键的组件叫代理注册表Agent Registry。它负责登记每一个代理的基础信息、能力范围、输入输出格式。# agent_registry.py 的核心数据结构简化为示意 dataclass class AgentSpec: name: str role: str # planner / executor / verifier capabilities: list[str] # [sql_query, http_call, file_io] input_schema: dict # 该代理能接受的输入格式 output_schema: dict # 该代理输出的标准格式 max_concurrency: int 1 # 并发上限 timeout_secs: int 120 agents: dict[str, AgentSpec] {} def register_agent(spec: AgentSpec): agents[spec.name] spec print(f[registry] agent {spec.name} registered, role{spec.role})这个注册表的重要性在于规划器在做任务分解时不是凭模型感觉乱分而是要先查注册表看当前系统里到底有哪些能力可用。没有注册表规划器可能会给你的子任务分配一个根本不存在的执行器或者让执行器干一件它没被授权干的事。2.3 任务消息流转不靠记忆靠结构化的任务对象在我之前的实现里代理之间传数据靠的是简短的 prompt 描述结果就是上下文被各种中间描述塞满了。而 agency-agents 里所有中间状态都被封装成了一个结构化任务对象Task Object。dataclass class Task: task_id: str owner_agent: str required_capability: str input_data: dict output_data: dict | None None state: str pending retries_left: int 3 created_at: float time.time()整个流程可以简化为规划器拿到用户目标拆解出多个 Task。每个 Task 被投递到对应的执行器。执行器完成后把 output_data 写回 Task。验证器检查 output_data 是否符合要求。如果失败Task 回到执行器重试或者回到规划器重新规划。这套机制下代理之间不需要互相猜对方“心里想的是什么”一切交流都通过 Task 对象这个明确的中介。这大大降低了上下文污染也让失败排查变成了单纯的日志分析。3. 任务编排的核心机制从自然语言指令到可执行计划三层架构搭起来之后核心的魔法都集中在规划器如何把一句自然语言指令变成一串可执行的步骤。这一步如果设计得不好后面全白搭。3.1 规划器的工作流目标解析、能力匹配、依赖排序规划器接收用户指令后要做三件事第一目标解析。它要把模糊的自然语言转成一个结构化的目标。比如“整理一份上季度的销售分析并发给管理团队”会被转换为目标生成销售分析报告可交付物Markdown报告邮件发送凭证时间范围上季度第二能力匹配。解析完目标后规划器会查询代理注册表看哪些代理能力组合起来可以完成这个目标。比如查询数据库需要sql执行器生成文本需要分析师代理发邮件需要邮件工具代理。如果没有找到匹配能力规划器应该在这一阶段就提出“能力缺口”而不是硬着头皮开工。第三依赖排序。子任务之间往往有先后依赖。比如“拿到销售数据”必须发生在“生成分析报告”之前“发送邮件”必须发生在“报告生成”之后。规划器输出的计划本质上是一个有向无环图DAG。虽然运行时不需要真的搞一个图数据库但内部必须维护好依赖关系。下面是我压测过一次的真实计划输出。用户输入是“看看昨天订单下降了没有如果下降了把原因和补救建议写成文档发给我”。{ tasks: [ {id: 1, agent: data_query_agent, action: run_sql, params: {sql: ...}}, {id: 2, agent: analyst_agent, action: analyze_downstream, params: {}, depends_on: [1]}, {id: 3, agent: writer_agent, action: write_doc, params: {}, depends_on: [2]}, {id: 4, agent: mail_agent, action: send_email, params: {}, depends_on: [3]} ] }3.2 执行器循环取任务、调工具、验输出、写回结果执行器在框架里是一个矢量的存在。每个执行器都对应一套工具functions。跑一个子任务的循环看起来非常简单# 执行器主循环伪代码 while True: task task_queue.get_executable_task() if task is None: time.sleep(1); continue # 调用具体的工具 API result invoke_tool(task.required_capability, task.input_data) # 先做一层硬校验格式对不对、必填字段有没有 if not valid_task_output(result, task): task.state failed task_queue.requeue_with_backoff(task) else: task.output_data result task.state done这里有个细节值得强调执行器不负责评判自己的输出质量。它只负责调用工具、拿到结果、做格式校验。至于这个结果到底对任务目标有没有用那不是执行器的职责是验证器的职责。这种“裁判和运动员分离”的原则是整个体系能够稳定不崩的关键。3.3 验证器的三个维度完整性、格式合规、语义一致性验证器有两种实现方式规则引擎和模型推理。一般的建议是优先用规则引擎拦截低级的、确定性错误只有规则引擎无法判断的错误才交给模型来评估。完整性检查的是每一个必须存在的字段是否都存在于输出中。比如报告有没有结论部分、附件有没有被生成。格式合规检查的是输出是否匹配注册表里定义的 output_schema。如果分析师代理承诺要输出JSON数组结果给了一段带注释的Markdown验证器必须立刻拦下来。语义一致性检查的是输出结果是否真的回应了原始任务的目标。这一步通常需要调用语言模型辅助判断也是整个链路里唯一比较消耗 token 的地方。提示语义一致性校验的阈值设置要谨慎设得太严格会把原本已经能用的结果反复打回重试白白烧掉 token设得太宽松又形同虚设。我的经验是先按 0.7 的相似度阈值起步再根据真实任务的成功率上下微调。3.4 状态机设计pending、running、blocked、done、failed任务状态机的设计是整个框架里最见功力的一块。agency-agents 里定义了五种状态状态含义可流转去向pending等待调度running, blocked, failedrunning正在执行done, failedblocked依赖外部输入或人工审批running, faileddone已完成无failed重试耗尽或不可恢复错误pending(重新规划)这个状态机不是拍脑袋设计的。它的精妙之处在于“blocked”状态。一个代理系统如果没有阻塞状态遇到挂起任务就只能不停地重试而有了 blockled 状态后系统可以明确区分“它只是在等别人”和“它出了问题”这对于运维监控来说是决定性的区别。4. 代理之间如何协作消息传递与共享记忆的取舍多代理协作的另一个大问题是代理之间如何共享信息。我在项目初期尝试过两种方式各有优劣最后在 agency-agents 里看到的是一个混合方案。4.1 黑板模式 vs 点对点消息谁更适合多代理工作流黑板模式Blackboard指的是所有代理共享一个公共的工作存储空间任何代理都可以往里面写内容、读内容。好处是实现简单所有信息一目了然坏处也很明显时间一长整个黑板会变成一团乱麻代理读取时根本分不清哪些是相关的、哪些是中间垃圾。点对点消息模式Peer-to-Peer指的是代理A把结果直接发给代理B中间不经过任何共享存储。好处是权责清晰A只关心把消息传给BB只处理A发来的消息坏处是当流转链路变长之后消息很容易丢失也没有一个全局视图知道现在整体进行到哪一步了。4.2 混合制里的核心一个不会爆炸的“工作区”agency-agents 用的是混合制不同代理之间通过明确的消息传递对接但同时有一块共享的、带生命周期的临时工作区用来存放跨代理共享的中间产物。这个“工作区”不是无限增长的它有以下两个关键约束每个 Task 写入工作区的数据必须声明自己的格式和过期时间。某个 Task 完成后它写入工作区的数据只能被下游 Task 读取一次读取后自动标记为“已消费”避免后续代理误用。# workspace.py 的设计示意 class Workspace: def __init__(self): self._store {} def write(self, task_id: str, key: str, value: Any, ttl_secs: int): self._store[f{task_id}:{key}] { value: value, expires_at: time.time() ttl_secs, consumed: False } def read_and_consume(self, task_id: str, key: str): full_key f{task_id}:{key} if full_key not in self._store: return None record self._store[full_key] if record[expires_at] time.time() or record[consumed]: return None record[consumed] True return record[value]在实际运行里这个设计解决了一个我头疼很久的问题代理从共享空间里读到了别人留下的过期数据还把它当新鲜输入用。有了 TTL 和 consume 机制后这类问题几乎绝迹了。4.3 协作模型的共享记忆格式化问题就算用了工作区协作模型里仍然有一个不能忽视的细节共享记忆的格式化问题。多个代理在同一个工作区写数据时如果没有统一的格式约定下游代理就会耗费大量 token 去解析和理解别人写的内容。我在第一次联调的时候遇到过这种问题销售分析师代理写出来的结果是 JSON 数组但数据分析师代理习惯用的是 Markdown 表格两个格式没统一导致下游的写作代理反复报错浪费了大量重试次数。后来我用了注册表工作区双保险每个代理在注册的时候除了声明能力还必须声明“我输出什么格式”。写工作区时系统会自动把代理的输出归一化成标准格式。下游读到的永远是一致的 JSON 结构格式混乱的问题就彻底消掉了。5. 稳定性治理循环失控、上下文膨胀、并发竞争三大高频事故多代理系统跑起来之后新的问题又冒出来了。这里集中说一下我遇到最多、也最影响稳定性的三个故障以及对应的治理办法。5.1 循环失控当代理开始“死循环”式重试第一个高频事故是循环失控。表现特征是执行器在调用某个工具时反复失败然后不停重试重试失败后又回到规划器重新规划规划出的新任务和旧任务几乎一样于是又投递下来形成无限循环。我记得有一次系统把一个简单的数据查询任务重试了二十多遍——不是重试一次两次而是二十分钟内连续完成两轮完整的“规划-执行-失败-再规划”循环把某数据服务的 API 配额直接打满了。治理办法有两个硬性标准全局步数上限。整个任务链路的执行步数一旦超过某个阈值比如40步系统必须强制熔断不允许任何代理继续行动。计划重复检测。规划器每次生成计划时会把计划的特征哈希保存下来。如果正准备执行的计划和五分钟前的计划哈希相同自动判定为“卡死循环”直接转为失败状态并通知管理员人工介入。5.2 上下文膨胀token 预算管理与关键信息摘要策略第二个高频事故是上下文膨胀。多代理系统比单代理更容易消耗 token因为每个代理都会把前一个代理的完整输出塞进自己的上下文里。如果中间步骤特别多整个链条的 token 消耗是指数级增长的。治理思路是从系统层面帮代理做“记忆封装”。当执行器A的输出需要传给执行器B时系统不会原封不动地把 A 的全部输出丢给 B而是先做一层摘要化处理只保留结构化输出中标记为“关键字段”的内容。把长文本部分用语言模型压缩成摘要。如果还携带了文件路径、链接等外部存储引用就只传引用不传正文。经过这三层处理后整个链路上的 token 消耗下降了约60%而且准确率反而提升了因为下游代理接收到的信息密度更高了。注意做摘要化一定要保留原始产物的完整版本并把引用路径传给下游。不能只传摘要因为下游如果需要引用原文里的某个具体数字摘要可能会丢失精度。我的做法是工作区里同时存完整版和摘要版。5.3 并发竞争多个执行器抢同一个任务或资源第三个高频事故是并发竞争。多个执行器并行跑的时候如果不加控制会出现两个执行器同时处理同一个 Task 的情况。还有一种情况是多个代理同时想调用同一个有限配额的工具导致接口互相限流。解决方案比较简单粗暴——加分布式锁配额控制。# 关键片段任务领取时的分布式锁Redis 示意逻辑 lock_acquired redis_client.set( ftask_lock:{task_id}, worker_id, nxTrue, extask_timeout_secs ) if not lock_acquired: print(ftask {task_id} already claimed by another worker) continue同时每个代理在执行前都要向流控组件申请工具配额像信号量一样限制并发量。这一步看起来不起眼但在有真实第三方 API 依赖的系统里直接决定了生产环境是稳定工作还是频繁 429。5.4 一次完整的事故排查任务明明失败了监控面板却显示“进行中”这里想分享一次印象深刻的排查过程完全能体现这套状态机的价值。那天我人工跑任务结果迟迟等不到最终输出。去监控面板看发现任务一直处于 running 状态日志里也没有任何报错。一开始我怀疑是模型调用太慢把超时时间调长了结果还是不行。后来我去翻执行器的详细日志发现这个执行器在调某工具时已经拿到了返回结果但工具返回的是一个超长字符串执行器在“写回工作区”这个环节卡住了——因为字符串太长序列化时间超长。又因为超时时间设置得不合理这个超时异常被静默吞掉了任务就一直挂在那里。修这个问题的关键动作有三个给工作区写入做了超时保护把工具返回的超长字符串截断存引用而不是正文增加监控规则任务在 running 状态超过阈值时长就自动触发告警。这也是为什么我一直强调代理框架不只是把 prompt 写漂亮就行工程上的细节才是决定成败的地方。6. 部署与调优真实环境里的参数推荐与扩展路线架构跑通、稳定性也有保障了最后聊聊落地部署时的一些参数和基础设施建议。6.1 一份可以抄作业的资源配置参考我根据自己的实际压测结果整理了一份不同负载下的资源配置参考表。纯知识型任务和小规模业务任务其实用不了太高配置但如果你开始做大规模推理或者多执行器并行就需要好好规划了。场景建议执行器数量模型规格推理工作区存储个人项目 / 测试环境1-2轻量模型即可满足本地 JSON 文件小团队内部分工具3-5中等能力模型按需搭配SQLite / 本地 KV生产环境 / 多任务并发10高性能模型分组配置Redis 对象存储跨地域多节点部署20多模型混合决策Redis Cluster 云存储我自己在生产环境里长期运行的是一套 6 执行器的集群方案模型按角色拆分——规划器用一个推理能力较强的模型执行器用响应速度快的模型验证器再单独用一个中等模型跑规则和语义判断。这样的分配方式在每个 token 的利用效率上会明显优于“一个模型干到底”的方案。6.2 先看工具耗时再看模型耗时最后看调度开销如果你也遇到了任务整体偏慢的问题排查的顺序一定不要乱。我个人的经验是按“工具耗时模型耗时调度开销”来逐层定位。第一步先看工具调用是不是慢线程。比如某个代理每次查询数据库都要 3 秒每次发 HTTP 请求要 5 秒那整体慢就是工具的问题先优化工具侧的并发和缓存。第二步再看模型推理耗时。模型越大、输入上下文越长等待时间越长。这里的优化手段就是前面说的摘要化、截断长文本、降低末尾的输出上限。第三步才是调度开销。当执行器数量很多时任务分配、锁获取、状态持久化的开销也会积累但这类开销通常占比极小如果前两步没问题基本不用考虑。曾有一次我把问题幻觉归咎于调度折腾半天装了一套复杂的事件分发系统结果发现瓶颈其实是一个工具没有设置连接复用。那一次的深刻教训是慢问题先从最底层的工具耗时开始怀疑。6.3 从单节点到多工作节点的演进哪些该前置哪些可以后置不是所有架构演进都适合从第一天就开始做。我见过很多项目上来就直接上 RabbitMQ Redis 一大堆工作节点结果连基本的任务流程都没跑通配置成本倒是花了几个星期。按照一个容易控制的演进顺序单进程、单工作节点用进程内队列适合验证逻辑正确性。分离独立的工具服务把数据库查询、HTTP 调用等服务拆分出去帮助定位问题。引入外部消息队列和共享存储有了多个节点后才需要引入以便解决状态同步问题。多节点部署注册中心动态扩缩容这一步是最后的优化环节因为业务规模到这一步再谈扩展性才更有针对性。前面三件事的优先级远高于第四件。如果你的系统还没有跑超过一百个任务完全没有必要在第四步上花时间因为多节点带来的资源损耗和心智负担可能比收益还大。6.4 几个改了以后立竿见影的默认参数最后分享一下我调完效果特别明显的几个参数。它们不一定具有普适性但可以作为初始值参考参数初始值调整后效果执行器超时时间60s120s减少无关的误报失败任务最大重试次数3次5次提高偶发错误下的成功率规划器计划重复检测窗口无300s彻底杜绝循环重试验证器语义一致性采样长度全文输出前2000字符降低校验延迟约40%工作区数据 TTL永久30分钟避免过期数据污染下游任务我在这里强烈建议如果想让这套系统更贴合自己的业务不要照抄任何一组默认参数而是先把跑批任务的历史日志找出来统计实际的任务失败率、平均耗时、重试次数分布再反推这些参数应该设成什么值。用日志数据驱动调参是避免“看着合理但跑起来还是崩”的最有效方法。最后说一个我个人用了很久的心得。很多人觉得多代理系统的核心是模型聪明不聪明但我做了这么久之后越来越觉得它更像搭一个靠谱的团队流程清晰、职责明确、出了错误可以定位、有了问题能追踪。给代理系统一套可被约束和追踪的“工作制度”它的稳定性和可用性才会真正上一个台阶而不仅是一次又一次地依赖更先进的大模型来兜底。如果你也在折腾多代理编排我的建议是先从最小的三层模型开始把一个任务完整走通再逐步加复杂度。很多问题不会在你只跑一颗假想任务时暴露优雅地在测试环境里的架构一到生产环境遇到真实的 API 限流、超时、数据格式不一致之后才会真正显露出价值。所以别怕开始时“土”先让它跑起来再让它跑稳。

多智能体框架agency-agents：架构设计与稳定性治理

相关推荐

斐波那契数列：从数学原理到编程实现

仿现代C++智能指针实现引用计数

斐波那契数列：从数学到计算机科学的奇妙应用

更多资讯

Pandas缺失值处理：类型识别、语义归因与工程化实践

YOLO系列全解析：从算法原理到部署实战

AI模型与算法区别及部署实践指南

DeepSeek-V4编程能力解析：从多语言协同到硬件感知代码生成

ComfyUI安装部署全指南：四层架构避坑实战

深度学习模型文件读写与格式转换实战指南

今日更新

基于YOLOv11的石油泄漏智能检测系统开发实践

AI行业变局：合规、Mod化与上下文管理的实战启示

计算机视觉与AI原生应用融合的技术实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？