Agent框架底层重构：模型网关、三层记忆与DAG编排实践

如果你也在做 Agent 开发大概率经历过这种尴尬Demo 跑得风生水起一上真实任务就各种幺蛾子。Orkas 是我这边维护了大半年的一个 Agent 框架主打多工具编排与长程任务执行。上半年有段时间线上任务频繁报错日志里清一色“agent execution terminated due to error.”用户反馈的语气也越来越冲。我花了两周排查最后得出的结论非常扎心问题不在模型也不在具体某个工具而在整个框架的地基——执行引擎、记忆体系和模型调用层这三层叠在一起像一盘散沙任何一层出问题上层就跟着雪崩。这篇文章就是 Orkas 这次底层重构的完整复盘。我会先把旧架构的结构性债务一条条摆出来再讲新地基的三层设计模型网关、三层记忆体系、DAG 编排引擎以及重构过程中踩过的坑和灰度策略。正准备从 0 搭 Agent 框架、或者正在被自家 Agent 稳定性折磨的朋友应该能从里面找到一些可以直接抄作业的思路。1. 重构的导火索一次凌晨两点的事故逼我掀了旧房子1.1 事故现场30% 的任务在深夜集体失败那天凌晨线上监控突然炸了。一个看似简单的任务——查询本周项目进度整理成周报发给负责人——在两个小时内有接近三成直接失败。失败日志非常统一都是那句让人血压升高的agent execution terminated due to error.。更让人头大的是另一个现象不少任务确实跑完了但跑了一个多小时Token 烧了十几万最后产出一份牛头不对马嘴的报告。用户原话是这个 Agent 像是没睡醒前面聊的好好的后面突然失忆了。我当时的第一反应是换模型。结果换了更强的旗舰模型失败率只降了一两个百分点Token 消耗反而更高。第二反应是查工具接口结果所有工具单独调用全部正常响应时间都在百毫秒级别。1.2 排查链路问题不在模型而在地基真正把问题挖出来是靠一帧一帧看执行链路日志。我梳理了失败任务的共同特征第一上下文越滚越大。任务执行到第 20 轮时整个上下文里塞满了中间推理过程和冗余的工具输出早期关键的项目进度数据反而被挤出窗口。模型不是不会做而是看不到关键信息了。第二工具返回格式一变化就崩。某个接口偶尔多返回一个字段下游解析逻辑直接抛异常。而旧架构的错误处理方式是异常向上抛任务整体终止没有任何局部重试或分支降级。第三执行流程是硬编码的。旧版用一串 if-else 把查询进度 → 提取要点 → 生成报告 → 发送串起来每一步都要手工指定下一步。这个任务的流程还算简单那些需要十几步的复杂任务代码里全是分支判断同事看了都摇头。我盯着这些日志想了很久意识到一个残酷的事实这些问题不是 bug是架构设计时就埋下的雷。往下拆无非三个层面——模型调用逻辑和业务逻辑焊死在一起、记忆体系是现用现拼的临时方案、执行编排是链式回调地狱。任何一个层面都会随着任务复杂度上升而爆炸三个一起爆就是我那天凌晨看到的样子。1.3 决定重构之前我问了自己三个问题重构不是小事尤其是一个已经跑在线的框架。我当时没有冲动行事而是冷静下来问了三个问题修补成本 vs 重建成本。局部打补丁能不能解决比如给上下文加个压缩模块给工具调用加个重试。答案是能缓解但复杂度会指数上升。每加一个特性就要在三个层面各打一个洞最后代码会变成一栋到处是补丁的危楼。旧债是否堵住了新特性的路。当时产品规划里已经列出了多 Agent 协作、长期记忆持久化、跨会话上下文恢复这三个方向。我评估了一下这三件事在现有架构上几乎做不动。记忆没有分层跨会话就是空谈编排是链式的多 Agent 并行就是空谈。调用方能否无感迁移。Orkas 当时已经接了好几个业务方API 层面不能推倒重来。如果必须让调用方改代码那重构的代价和风险就完全不同了。三个问题想清楚后结论很明确局部修补只是续命底层重建才是出路。但重建不是把旧代码删掉重写一遍而是先在旧系统的旁边把新地基搭起来然后通过兼容层和灰度逐步切换。这个思路贯穿了整个重构过程。2. 旧地基到底烂在哪三条结构性债务的详细解剖2.1 模型调用逻辑和业务逻辑焊死在一起旧版 Orkas 最大的问题是调模型这件事散落在每个业务函数里。写一个工具函数里面可能就夹着一大段 prompt 拼接和 LLM 调用代码。今天用 A 厂商的模型接口明天换 B 厂商就要把全项目翻一遍想统一加个限流找不齐到底有多少个入口在调模型。更可怕的是上下文管理完全失控。每个 Agent 自己维护一份对话历史有的用列表存全部消息有的只存最后五轮有的甚至把工具返回的原始报文整个塞进去。没有统一的 Token 预算没有压缩策略没有超限保护。结果就是任务一长输入长度爆炸模型的注意力被稀释行为变得飘忽不定。这也是为什么我后来断言问题不在模型在地基——同一个模型喂给它的上下文质量天差地别表现自然天差地别。模型调用层必须从业务中剥离出来变成一个统一收口的网关所有流量都从这里进出才好集中治理上下文、限流、重试和降级。2.2 记忆体系是现用现拼的临时方案旧版所谓的记忆就是两个东西一个放在内存里的chat_history一个全局context字典。任务跑完进程一重启记忆归零。用户上次说过的偏好、之前任务沉淀下来的结论全都丢了。这个设计带来的连锁反应是长对话只能把所有历史都塞给模型导致费用和延迟双双失控跨会话恢复完全靠外部业务方自己拼 prompt相当于把记忆的责任甩给了调用方更别提什么记忆检索——旧系统根本没有检索只有全量注入。当时我也调研过社区里关于短期、长期、永久记忆的各种讨论其实核心思路是一样的不同记忆的访问频率、重要程度、生命周期完全不同不能一锅炖。短期记忆要快读快写、短期存活长期记忆要能检索、要跨会话永久记忆要结构化、要可审计。旧版不具备这个分层能力所以在记忆体系上推倒重来是没有悬念的。2.3 执行编排是链式回调地狱旧版的执行编排本质上是一条链工具 A 的输出作为工具 B 的输入一层层往下传。代码里用Chain对象把它们串起来每加一个新任务就要手工写一条新的链。这个模式在小 Demo 里毫无问题但一旦任务复杂起来就全是坑所有步骤严格串行明明查项目进度和查团队空闲情况可以并行链式结构却只能排队执行。中途任何一个步骤失败整条链直接断掉没有局部重试也没有分支绕行。错误处理全靠 if-else 堆每个节点都要考虑失败了我该走哪个分支代码越写越复杂。多 Agent 协作无从谈起。多个子 Agent 的依赖关系、汇合逻辑、结果整合在链式模型里根本表达不出来。我在设计新引擎时第一条原则就是执行编排必须从链式变成图。任务天然是有依赖关系的一组步骤只有图结构才能表达并行、分支、汇合和失败域。3. 新地基第一层模型网关层把调模型变成发消息3.1 统一协议内部收口重构后的 Orkas最底层是一个统一的模型网关内部抽象出了ModelGateway接口。所谓统一不是说只用一家模型厂商而是把各家模型接口都包成同一种语义chat(messages, tools, params)对话补全embed(texts)向量化tool_call(messages, tools)强制工具调用所有业务模块——编排引擎、Agent 运行时、记忆模块——都只能通过这个网关访问模型不允许任何人绕过它直接拼请求调上游 API。好处非常直接模型厂商切换变成配置项限流和熔断在网关层做一次就全局生效Token 消耗统一计量再也不用来回翻代码找到底哪个模块在偷偷调模型。这个设计参考了消息队列的思路业务方不需要关心发给谁、走什么协议、怎么保证可靠只负责把消息丢进队列。模型网关就是 Agent 内部的消息队列把底层模型的差异全部吞掉。3.2 上下文治理Token 预算与注入策略网关层最核心的职责之一是上下文治理。我给它划了几条硬规则第一每个任务都有 Token 预算。比如设定单轮最大输入 12000 Token超了就必须触发上下文压缩策略而不是无限膨胀。压缩策略分三档先丢弃最早的历史消息再对中间推理过程做摘要最后把工具返回的冗长报文替换成字段名关键值的精简形态。第二记忆注入优先走检索而不是全量注入。旧的上下文管理把历史消息当成唯一的信息来源重构后引入按需检索任务开始时根据当前目标去记忆库检索 top-k 条相关记忆再拼接进上下文。这直接砍掉了大量无效 Token。第三强制设硬上限。即使压缩策略全部失效单轮输入也不能超过某个绝对值比如 24000 Token超过时任务必须停下来向调用方告警而不是硬撑着继续跑。这一层治理做完之后最直观的变化就是 Token 消耗直接降了大概 40%模型的失忆现象也大幅减少——因为它终于能在窗口内看到该看的信息了。3.3 失败重试与模型降级链模型调用是外部依赖外部依赖就一定会抖动。旧版的做法是失败就抛异常重构后的做法是在网关层内置三级容错指数退避重试瞬时错误限流、超时自动重试间隔从 500ms 开始翻倍增长最多 3 次。熔断连续失败超过阈值网关直接进入熔断状态快速拒绝新请求避免把上游打挂。模型降级链给每个任务配置一个模型列表例如主力旗舰模型 → 备用快速模型 → 本地小模型。主力模型连续失败时自动切换下一个。这套容错机制是重构后见效最快的一层。只加了这个功能线上任务的execution terminated due to error比例就肉眼可见地降了下来因为大量失败其实不是模型不会做而是调用链路里的瞬时抖动被当成了致命错误。4. 新地基第二层三层记忆体系的重建4.1 短期工作记忆会话内的草稿纸短期记忆对应的是 Agent 在当前会话内的活跃状态。我把它拆成三块最近 N 轮对话消息存在 Redis 里键名带会话 IDTTL 设为 30 分钟。当前任务栈正在执行的子任务列表、每个子任务的状态、当前执行到的节点 ID。临时变量区工具返回的中间结果、用户中途补充的信息、推理过程的短暂缓存。短期记忆的读写路径必须极快因为每一轮执行都要访问。它不追求持久化进程挂了可以重建但一定要保证单轮内的读写一致性。这里我踩过一个坑最初用纯内存字典存短期记忆快是快但执行引擎一旦重启所有在线会话全部断了。后来改成 Redis 本地缓存双写本地命中Redis 兜底才算真正稳下来。4.2 长期记忆跨会话的笔记本长期记忆解决的问题是用户上周跟你说过的偏好这周再来的任务Agent 应该还记得。它的核心是两条记忆提取每个任务结束后执行一次 memory consolidation从会话中提取值得记住的要点——用户明确的偏好、项目背景的关键信息、任务产生的结论。提取可以靠一个专门的小模型调用来完成也可以靠规则 关键词来兜底。记忆检索新任务启动时根据当前任务目标生成检索向量从长期记忆库中召回 top-k 条最相关记忆注入上下文。长期记忆的存储我用的是向量库 结构化事件表的组合。向量库管语义相似的记忆结构化事件表管有明确属性的记录比如用户偏好格式周报里有数据表这种直接查字段比向量检索更准。向量库我选的是 pgvector没有额外引入新组件直接在现有 PostgreSQL 里开扩展运维成本几乎为零。如果你从零搭建Milvus 或者 Qdrant 也都可以核心是别把长期记忆做成一张大杂烩表一定要分语义检索和结构化查询两条路走。4.3 永久记忆可审计的档案柜永久记忆是最重的一层存放组织级知识库、用户身份画像、关键事件日志。这些数据的特点是几乎不被日常推理直接读取但必须在需要时能被精确查出而且必须可审计、可追溯。我把永久记忆放进了对象存储 数据仓库的组合里。对象存储存原文/原文件数据仓库存结构化的索引和摘要。写入永久记忆必须走审批接口不允许 Agent 在执行过程中随意写入——这是为了避免 Agent 被恶意注入的指令污染永久记忆区。说到这必须提一句安全边界这三层记忆的写入权限是逐层收紧的。短期记忆 Agent 可读可写长期记忆 Agent 可读写入要走 consolidation 流程永久记忆 Agent 只读写入只能通过管理员接口。社区里讨论的agent 安全 标签a-memguard 这类针对 LLM Agent 记忆的防御框架核心思路都是在记忆读写链路上加防护层。我当时做的是粗粒度的权限隔离后续可以往记忆内容本身就是不可信输入需要校验和过滤这个方向继续深化。5. 新地基第三层从链式调用到 DAG 编排5.1 为什么必须是 DAG而不是别的这是整个重构里花时间最多的决策。我评估过几种方案状态机、链式、事件驱动、DAG。最后选了 DAG理由有三条表达力。任务是由一组带依赖关系的步骤组成的图结构可以精确表达步骤 C 依赖 A 和 B 的结果等 A、B 都完成才能执行这种天然并行关系。链式做不到这一点。失败域隔离。DAG 里每个节点都是独立的执行单元一个节点失败可以只重试这个节点或者走这个节点的备选分支而不影响已经完成的兄弟节点。这在链式结构里是完全不可能实现的。可观测性。图结构天然适合做全链路追踪——每个节点对应一个 span节点之间的依赖关系对应 span 之间的父子关系。排查问题时顺着拓扑图一眼就能看出堵点在哪。DAG 不是没缺点最大的缺点是执行顺序自由了但编程模型变复杂了。所以我做了一件事把 DAG 藏起来对外暴露的仍然是很简单的 API——run(goal, tools)。用户不需要手写 DAG框架根据目标和工具列表自动构建执行图。5.2 节点状态机与调度器的实现细节DAG 里的每个节点有一个统一的状态机状态含义转移条件PENDING等待执行所有前置节点进入 SUCCEEDEDRUNNING执行中调度器分配线程开始执行SUCCEEDED执行成功节点函数返回正常结果FAILED执行失败节点函数抛出异常或返回错误标志TIMED_OUT执行超时超过节点级超时时间SKIPPED跳过条件分支判断为不满足调度器的核心是拓扑排序 并发调度。每次调度扫描所有 PENDING 节点检查前置依赖是否全部 SUCCEEDED是则放入就绪队列。就绪队列里的节点由线程池执行并发数用信号量控制——不是越多越好毕竟每个节点都可能触发模型调用并发太高容易打爆上游。节点级超时是我强烈建议你一定要做的。旧版是整个任务一个总超时结果一个工具卡住了整个任务卡住。新版每个节点都有独立的超时配置比如工具调用 30 秒模型推理 60 秒子 Agent 执行 300 秒。超时后节点进入 TIMED_OUT调度器根据配置决定重试、走备选节点还是终止整个任务。5.3 多 Agent 协作与 Skill/Harness 的分工DAG 编排带来的另一个红利是多 Agent 协作终于有了落点。在 Orkas 里一个子 Agent 本身就可以是 DAG 里的一个节点。父任务把子任务下发给子 Agent子 Agent 内部又是一个独立的 DAG 执行图执行完把结果汇报给父节点。这个层级嵌套在旧链式结构里是根本做不出来的。这里顺便把社区里经常混淆的三个概念说清楚——Agent、Skill、HarnessAgent是一个运行时实体有自己的状态、记忆和执行循环。它可以被理解为自主干活的人。Skill是预置的能力模板把常用 Prompt 工具集 参数校验规则打包成可复用模块。相当于给这个人的职业技能包装了就多一项技能。Harness是承载 Agent 的容器/外壳负责生命周期管理、资源隔离、输入输出边界。可以说它是这个人的工位和环境。在 DAG 编排里Skill 被映射为可复用的子图模板——你不需要每次都从零构建一个复杂节点直接引用一个 Skill框架自动展开成子图。Harness 负责子 Agent 节点的生命周期主节点可以等待子 Agent 完成也可以在超时后决定吞掉子 Agent 结果继续跑还是整体失败重来。6. 重构过程中的血泪清单兼容层、灰度与观测6.1 兼容层老调用方必须无感切换重构最怕的就是推倒重来业务方被强行绑架。我在新引擎旁边做了一层 Adapter旧 API 的所有入口保持不动内部转成新引擎的调用。业务方的 Python SDK 几乎没改只更新了配置项。Adpter 层重点是做好参数翻译和错误语义映射。旧版的错误码是一串字符串新版改用结构化错误对象Adapter 层要把新错误对象翻译回旧字符串不然调用方已有的错误处理逻辑全部失效。这个细节没做到位的话表面无感实际全是碎玻璃。6.2 影子模式与对拍先证明新引擎不更烂我从来不信重构完直接切流量这种操作。Orkas 的灰度分了三步走第一步影子模式。线上真实流量复制一份发给新引擎但新引擎的执行结果只落日志不返回给用户。风险为零目的只有一个看新引擎跑同一条链路会不会崩性能和 Token 消耗是多少。第二步对拍。同一批任务同时发给新旧引擎拿两边结果做质量对比。对拍不是人工看一遍而是用一组可量化指标任务是否完成、完成时长、工具调用次数、Token 消耗、用户侧反馈。连续跑一周确认新引擎在成功率、延迟、成本三个维度上都不弱于旧引擎。第三步增量放量。流量切 5%、观察 24 小时、切 20%、再观察、切 50%最后全量。任何一个环节出现指标负向漂移立即切回旧引擎。这套流程走下来大约用了三周。期间最大的收获不是新引擎终于上线了而是锻炼出了一套完整的对拍基础设施——构建这个基础设施花的精力比写新引擎本身还多。6.3 全链路观测从报错不知道在哪到一键定位旧版排查问题靠的是大海捞针式地翻日志。新版我从第一天就把 OpenTelemetry 打进了引擎每个 DAG 节点都生成一条 trace span记录节点 ID、输入摘要、输出摘要、耗时、Token 消耗。这样再看那条 agent execution terminated due to error.排查路径就完全不一样了打开 trace看是哪个节点超时、哪个节点返回了错误、哪个环节开始 Token 超预算基本是直达病灶。插件配置字段冲突这类问题也类似——新引擎所有配置都过 JSON Schema 校验配置错了在启动阶段就报警不会等到运行期才炸。6.4 安全边界工具调用必须做权限隔离Agent 能调用的工具越多安全风险越大。Orkas 重构后做了两件事第一工具注册表 权限策略。每个工具在注册时必须声明自己属于哪个权限域只读、业务写、管理操作、危险操作。Agent 发起工具调用时引擎先做一次 policy check不在白名单里的调用直接拒绝。第二工具返回内容做长度和格式校验。防止一个工具返回超大报文把上下文撑爆也防止工具返回格式异常导致解析器崩溃。校验不通过时按降级处理走截断、摘要、或标记为失败并重试。这两条看似简单但实际上把很多潜在的越权执行和上下文污染堵在了门外。每次工具调用都像过安检虽然多了一层检查开销但对整个系统的稳定性帮助巨大。7. 重构之后实测数据与后续演进方向7.1 重构前后的关键指标变化这里放一组我在内部压测和对拍时记录的数据供参考指标重构前重构后任务整体成功率68%92.5%平均完成时长22 分钟9 分钟单任务 Token 消耗100%基准61%工具调用失败率15.3%4.8%因上下文超限导致的任务失败显著几乎归零这组数据的提升不是某一个模块的功劳而是三层地基共同作用的结果。成功率上升主要靠模型网关的降级与重试时长缩短主要靠 DAG 并行和记忆检索减少无效轮次Token 下降主要靠上下文治理和记忆按需注入。7.2 下一步想做的事地基重构完Orkas 的迭代速度明显快了。后续几个方向我已经在推进第一记忆体系的深度治理。现在的三层记忆还是写完就存、存完就查的朴素模式。下一步要加记忆衰减长时间不访问的记忆自动降权、记忆合并多条相似记忆自动去重归并、记忆冲突检测新记忆与旧记忆矛盾时如何裁决。这个方向也是最近社区里讨论 Agent 记忆时的热门话题。第二动态 DAG 改写。现在 DAG 是任务开始前构建好的一旦跑起来结构就不变了。但我希望 Agent 在执行过程中根据中间结果动态添加新节点、跳过某些分支、甚至重新规划后半段路径。这等于让 Agent 从按图施工进化到边看边施工。第三评测体系。重构的过程中我深刻体会到一个道理Agent 框架的演进速度取决于你有多快能判断新改动是变好还是变坏。所以接下来会搭建一套离线评测集涵盖多任务模板、多模型配置、多难度梯度每次改动先跑评测再决定是否上线。最后再说一句个人体会重构 Orkas 的这大半年我最深的感触不是技术方案多重要而是给 Agent 搭地基时永远不要为了省事牺牲边界的清晰度。模型调用、记忆、编排这三层的职责一旦模糊短期是省了代码量长期就是无穷无尽的线上事故。如果你也在做类似的 Agent 框架希望这次复盘能帮你少走一些弯路。