先说一个让我印象特别深的凌晨。那天监控弹了一条橙色告警Orkas 里一个跑了四个小时的 Agent 任务直接卡死——进程没崩日志却像被什么堵住一样半小时没有任何新输出。点开调用链发现它卡在三个Agent互相握手的地方A在等B的返回B在等C的确认C又在等A释放资源三个智能体彼此干等把整个编排线程活活饿死了。这不是第一次了每当我部署长对话、多轮协作、记忆膨胀之类的场景Orkas 这套老Agent框架就会冒出一堆难以名状的“抽风”。后来我下定决心不再给旧架构打补丁而是彻底做一次底层重构。这篇文章就是把 Orkas 重构的完整过程摊开讲一遍。你如果也在做 Agent 框架或者 Agent 平台或者正在纠结“要不要重写自家那套越来越难维护的 agent 底座”可以参考一下我的思路——哪些地方值得动、哪些地方坚决不能动、动了之后怎么保证老项目不掉地上。我不打算写成一篇普适性的架构教程而是以 Orkas 这次真实经历的每个关键决策为线索把底层重构中最容易被低估的坑一个个挖出来。1. 旧地基的问题清单为什么非重构不可1.1 一场“循环等待”事故暴露的编排脆弱性那次凌晨的事故排查到最后很有意思三个 Agent 都活着各自的模型调用也都正常返回问题出在它们之间的协作方式。旧版 Orkas 用的是最朴素的同步 Request-Reply 模型。Agent A 需要调用 B 的结果就直接发一个带超时的请求B 在处理过程中又去请求 CC 的某个前置条件需要 A 先完成。三个请求凑在一起形成了一个标准的循环等待而且每次等的时候占用的都是真正的工作线程。于是整条链路上所有 Agent 全部“悬空”日志里除了等待没有别的东西。根因不是某一个 Agent 写错了而是编排层对 Agent 之间的依赖关系完全没有建模能力。它只能表达“谁调谁”表达不了“谁需要谁什么状态才继续”。同步阻塞模型在组件少、链路短的时候很直观一旦 Agent 数量到 5 个以上任何一条链路的异常都会牵连全局。当时我用一个粗糙的脚本统计了线上任务的全链路超时分布发现有接近 12% 的失败任务并不是模型或工具出错而是 Agent 之间同步等待导致的超时。这 12% 就是纯纯的架构债。1.2 记忆全堆在上下文里长对话直接崩比编排死锁更普遍的是记忆系统的偷懒。旧版 Orkas 的记忆实现非常“天真”对话历史、中间推理结果、工具返回内容一律拼进 Prompt 的上下文窗口里。模型窗口 128K 的时候还能勉强跑一旦任务变成多轮长对话上下文就迅速膨胀。我有一次跑一个“市场调研 竞品分析 报告撰写”的综合任务单轮对话 token 干到了 9 万仅 Prompt 拼接就花了接近 2 秒更别说模型推理的成本。更麻烦的是全量堆上下文不只是浪费钱它会让模型注意力发散。比如 Agent 在第 30 轮需要回忆“用户第一次提到的预算约束”但如果这中间夹杂了 20 次工具调用结果和 15 段无关闲聊模型经常会把某个工具的返回数字误当成预算约束。质量肉眼可见地下降。这也是我后来决定把记忆系统彻底重做的直接原因。记得在吴恩达的 Agent 教程里有一句话特别到位记忆不是把聊天记录存下来而是要把“当前任务需要的上下文”和“长期沉淀的事实”分开管理。旧 Orkas 就是完全没有做这个切分。1.3 多 Agent 协作时的“广播风暴”旧版 Orkas 的协作模型是“共享黑板”。每个 Agent 可以把消息写到一块公共区域其他 Agent 自由订阅。听起来很灵活用起来是灾难。举个真实例子市场分析 Agent 发布了一条“竞争对手价格更新”的消息产品 Agent 订阅了价格变化、研发 Agent 订阅了所有市场动态、运营 Agent 订阅了全部黑板消息结果一条消息被重复处理了三次其中两次处理还产生了新的消息又继续往下游广播。整个协作网络像没有刹车的下坡车越跑越快。最后整个任务因为消息队列积压直接 OOM。设计者的本意是好的想用发布订阅解耦 Agent 之间的直接依赖。但问题在于黑板模型没有“谁应该对什么负责”的边界消息一旦发布转发链完全失控。协作场景需要的是有明确目标的调度不是无差别的广播。1.4 重构的边界不是推翻重来整理完这些罪状之后团队里有一个声音是“全部推倒重写”。我第一个反对。Orkas 毕竟已经跑了不少线上任务对外暴露的 API、插件机制、部分 Agent 应用都是能用的。全部推倒意味着所有老集成方都要跟着迁移成本巨大而且新系统未必能一下子覆盖旧系统所有细节。我们最后确定的重构原则是三条保留对外协议和稳定 API尤其是 Agent 的标准输入输出格式、事件上报格式、插件加载规范。重建内核包括任务编排、状态管理、记忆管理、工具调度这四个核心模块。能力层不做大规模重写已有 Agent 应用尽量少动通过适配层接入新内核。说白了这一次是“换心脏不换骨架”。骨架上的血管、神经可以慢慢接但心脏必须是新的否则其他手术都是白做。这也让我后面在写兼容层、迁移方案时有了清晰的边界。2. 破土动工Orkas 新架构的核心设计2.1 三明治分层运行时、内核、能力重构后的 Orkas 在代码组织上做了一个非常清晰的“三明治”分层。最底层是运行时Runtime负责进程生命周期、线程池、异步事件循环、定时器这些跟业务无关的基建。中间层是内核Kernel包含 Agent 状态机、任务调度器、记忆管理器、工具注册表、事件总线。最上层是能力Capability也就是具体的 Agent 实现、MCP 适配器、第三方插件。这个分层最有价值的地方在于无论是 Agent 还是插件都只能依赖内核暴露的接口不能直接摸到运行时。以前旧版代码里常常出现 Agent 内部直接起线程、直接操作数据库的“越权行为”在新架构里根本不可能因为能力层拿不到那些句柄。以 Python 为例我们给能力层暴露的是一组只读的 Context 对象dataclass class AgentContext: agent_id: str memory: MemoryManager tools: ToolRegistry events: EventBus state: StateHandle # 只读状态只能查询不能直接改没有任何字段是 Agent 可以直接赋值的。想更新状态必须通过state.transition()方法走状态机校验。这个约束在重构初期带来了很多“开发不变”的抱怨但后期几乎所有人都认可了因为它让系统行为变得可推理。2.2 事件驱动取代线性调用旧版 Orkas 的 Agent 之间是方法调用关系A.execute() 里直接调 B.execute()。这个方法调用链一旦长起来连排查问题都困难因为你根本不知道当前是哪个栈帧。新内核把 Agent 之间的交互全部改成了异步事件。每个 Agent 有自己的事件收件箱事件一旦产生就投递到对端信箱由调度器决定何时唤醒目标 Agent 处理。这里我要特别说明一个容易踩的坑事件驱动并不等于“发消息就行”。如果只把原来的方法调用改成发一条事件消息没有任何推进机制那整个系统会变成一堆永远在“收件箱待处理”的僵尸 Agent。因此 Orkas 的事件总线里内置了“推进合约”。每类事件必须携带明确的意图标记比如RequestReply、FireAndForget、ScheduleWake。调度器看到RequestReply会自动建立请求-响应的关联看到ScheduleWake会把目标 Agent 放入延时队列时间到了再唤醒。这样事件驱动才不只是通信方式的改变而是编排语义的重建。2.3 显式状态机所有 Agent 的状态不再靠猜旧版 Orkas 判断 Agent 是否忙靠的是一个布尔字段is_busy。现在听起来蠢但当时确实就是这么设计的。Agent 忙不忙、在干嘛、卡在哪个环节全凭 agent 内部的日志去猜。重构后的内核给每个 Agent 建立了一套显式状态机。状态定义如下状态含义可迁移到idle空闲等待调度planningplanning正在生成计划/思考下一步tool_calling / waiting / respondingtool_calling正在执行工具调用observing / waiting / failedwaiting等待外部事件人、消息、定时器planning / timeoutresponding正在生成回复idle / failedpaused主动挂起等待人工恢复planning / idlefailed任务失败进入兜底idle重试所有状态迁移都必须在StateHandle.transition()里声明合法路径。非法迁移直接抛异常。这个设计帮我解决了一个很头疼的问题以前 Agent 卡住我只能看日志猜它在干什么现在只要看一眼状态立刻知道它在tool_calling里卡了 5 分钟还是waiting里等了 5 分钟。线上排查效率高了一个数量级。2.4 可观测性从第一天就内置重构时我们把可观测性做成了内核的一部分不是后补的插件。每个任务从进入系统开始就分配一个全局trace_id所有事件、状态迁移、工具调用、记忆读写都带着这个追踪标识。我用 OpenTelemetry 做链路导出把关键 span 画出来。比如一个 Agent 任务的生命周期会是# 伪代码表达追踪结构 agent:task.start agent:state.enter(planning) agent:memory.read(user_goal) agent:tool.call(web_search) agent:tool.return(web_search, latency1200ms) agent:state.enter(responding) agent:task.end(statussuccess, total_latency8432ms)这套追踪体系在迁移期间帮了大忙。灰度对比时我只需要对比新旧系统同一任务在每条 span 上的耗时分布就能精准定位新内核哪个环节比旧系统慢完全不需要猜。3. 记忆系统的底层重写短中长期分离3.1 旧实现为什么撑不住旧 Orkas 的记忆就是“一个列表”。所有对话、工具结果、中间推理全往里塞最终整体进入 Prompt。这个实现最大的问题是没有任何遗忘机制。人也不会把三年前的一顿饭吃了什么放进当前对话的“工作台”里但旧版 Orkas 会把三个月前的聊天记录和最新工具返回全部压进上下文。模型被迫处理大量无关信息推理质量下滑、成本飙升、延迟变大三重暴击。说个直观的数字重构前一次 20 轮会话的平均 Prompt 长度约 4.2 万 token其中真正对当前回复有支撑作用的我抽样统计下来不到 15% 是有效信息其余全是历史噪声。3.2 三层记忆的存储与检索设计重构后我把记忆拆成了三层短期记忆、中期记忆、永久记忆。短期记忆放在进程内存里用环形缓冲区实现。它只保存当前任务窗口内的最近 K 条消息和工具结果容量上限由配置控制超过就淘汰最老的。短期记忆的特点就是“快”读写纳秒级不参与任何持久化。中期记忆以向量数据库为底座保存经过压缩的会话摘要、实体关系和阶段性结论。Agent 需要跨轮次引用信息时先做向量相似度检索取出最相关的若干条摘要拼进上下文。我的实现里用了 SQLite 向量扩展来存储避免引入重型组件。永久记忆则落到关系型数据库保存用户画像、关键偏好、跨会话的长期事实。比如“用户在预算上非常敏感”“用户公司目前 200 人规模”这类一旦确认就很少改变的信息。永久记忆只有在系统认为某一事实足够重要且置信度高时才会写入宁缺毋滥。三层记忆的分工非常明确短期负责“此刻”、中期负责“本轮任务”、永久负责“跨会话”。每层都有独立的写入策略和过期策略不再把所有东西都塞进同一个口袋。3.3 记忆压缩与上下文窗口的博弈记忆系统设计里最考验工程能力的是怎么压缩中期记忆。我采用的是“递归摘要 关键事实抽取”组合策略。每次对话达到一定轮次系统会调用一次摘要模型把这段时间的对话压缩成 200300 字的摘要同时抽取其中的关键事实写入永久记忆库。下一次需要回顾时不是取原文而是取摘要加相关事实。这里有个性能优化的小技巧摘要模型的调用本身也消耗 token如果每个 Agent 每 5 轮就做一次摘要成本也很可观。我在实现里加了“记忆预算”机制类似一个 token 账户只有短期记忆缓冲区快满时才触发压缩避免频繁压缩。在上下文组装阶段我还做了一个优先级排序永久记忆中的高置信事实 中期记忆中的高相关摘要 短期记忆中的原始片段。按这个顺序填充优先保证对回复最有利的信息进入上下文。3.4 实测效果token 消耗下降三成重构记忆系统后我拿同一批线上任务做了 A/B 对比。结果非常直观20 轮长会话场景下平均 Prompt 长度从 4.2 万 token 降到约 2.6 万 token降幅接近 38%模型回复的准确率按人工抽检比较反而提升了因为上下文里不再有大量干扰信息。最让我惊喜的是一个调研类 Agent以前跑到第 15 轮左右就开始“忘事”用户第一次提到的预算约束后面经常被无视。重构后加了永久记忆锚点这个约束在 30 轮之后依然被稳定引用。记忆系统不再是简单的存储而是真正成了 Agent 能力的放大器。4. 编排引擎再造从“传话”到“调度”4.1 多 Agent 协作的三种模式编排引擎是整个内核里最复杂的一块也是这次重构工作量最大的部分。我先把协作模式归纳成三种分别建模实现。第一种是主管-下属模式Orchestrator-Worker一个主 Agent 负责任务拆分、派活、汇总其他 Agent 各自执行子任务。这是最常用的协作模式适合调研类、报告类任务。实现上主 Agent 作为调度者每次派活就是发一个带着明确产出规范的RequestReply事件等下属返回结构化结果。第二种是互助模式Peer-to-Peer两个 Agent 地位平等互相交换信息、协商结论。典型场景是“财务 Agent 与法务 Agent 一起审一份合同”。实现上要给两个 Agent 建一个共享会话通道限定它们只能在通道内交换消息避免消息扩散。第三种是群聊模式Debate/Collaboration多个 Agent 围绕一个议题轮流发言。这种模式最考验调度器的公平性——不能让某一个 Agent 垄断发言权。我的做法是给每个参与者一个时间片超时未发言自动跳过。4.2 可挂起的任务Agent 也能“等一下”重构前Orkas 的 Agent 任务只有两种结局成功或失败。遇到需要等待人工确认、等待定时器触发、等待外部系统回调的场景只能空转轮询白白烧 token。新内核给 Agent 增加了一个灵魂能力waiting状态和挂起/恢复机制。Agent 在运行过程中可以显式请求挂起把当前状态完整保存释放计算资源等触发条件满足后再被唤醒从挂起的位置继续执行。这个机制的实现依赖状态机的持久化能力。Agent 挂起时内核需要把它的当前计划、已执行步骤、待办队列、上下文快照序列化保存。恢复时按照快照重建所有上下文对象然后重新进入planning状态生成后续步骤。我这里用了一个非常朴素可靠的方案状态快照直接存 JSON每个 Agent 一个版本号恢复时校验版本。不搞复杂的增量快照因为 Agent 挂起通常发生在人类审批环节频率不高全量序列化的开销可以接受。4.3 ReAct 循环的分步执行编排引擎处理单个 Agent 内部执行时核心是 ReAct 循环的工程化改造思考Thought→ 调用Action→ 观察Observation→ 再思考直到产出最终答案。旧版 Orkas 把整个 ReAct 循环放在一个巨大的 while 循环里一次模型调用、一次工具执行、结果再喂回模型碰到工具长期不返回就只能一直阻塞等待。新内核把这个循环拆成可中断的步骤调度。每一步都是一个独立的任务调度器决定什么时候执行思考、什么时候执行工具、什么时候进入观察。工具调用被设计成异步任务Agent 发起工具请求后可以暂时进入waiting工具返回后再唤醒进入observing然后继续下一轮思考。实际效果是单个 Agent 内部也可以实现并行优化比如某一步需要同时查三个数据源Agent 可以在一个循环里发出三个工具调用然后挂起等所有结果回来总耗时从串行的 9 秒压到并行后的 3.5 秒。上下游沟通的协作成本大幅下降。4.4 失败注入测试逼出隐藏问题重构编排引擎之后我特意引入了一套失败注入测试这是我觉得所有 Agent 框架团队都应该做但极少做的事。思路很简单在测试环境随机中断消息投递、随机注入工具调用延迟、随机让某个 Agent 状态迁移失败然后观察整个系统能不能自动恢复。第一次跑失败注入测试时结果惨不忍睹。有一个场景是主 Agent 派活给下属 Agent下属工具调用失败返回failed但主 Agent 还在傻等结果没有任何超时感知整个任务卡死。这个场景在旧版里也存在只是触发概率低一直没暴露。修复方案是在编排引擎里增加了“全局看门狗”。每个等待状态的 Agent 都登记一个期望唤醒时间超时未唤醒的会被调度器强制唤醒并进入失败重试流程。看门狗机制上线后这个场景的恢复时间从“永不恢复”变成了 3 秒内自动重试。事后复盘我强烈建议做 Agent 框架的同行把失败注入测试纳入 CI 流程而不是依赖线上偶然踩坑。5. 工具层与生态适配MCP 成为一等公民5.1 统一的工具抽象Agent 的能力最终体现在工具调用上。旧版 Orkas 的工具定义五花八门有同步函数、有异步回调、还有直接调外部 HTTP 接口的实现方式不统一排查问题极其痛苦。重构后我把所有工具收敛成一个统一的异步接口class BaseTool: name: str description: str input_schema: dict async def execute(self, arguments: dict) - dict: 执行工具并返回结构化结果 ...所有工具都返回相同的结构{status: success | error, data: ...}。成功和失败的表达统一了编排层的错误处理就简单了。同时这个接口天然兼容 OpenAI 的 function calling 格式老集成方如果本来就是用 OpenAI 格式定义工具的迁移成本几乎为零。5.2 并发工具调用与限流新内核支持一个 Agent 在同一轮发出多个工具调用并且并发执行。这个特性在编排上带来一个绕不开的问题并发限流。如果对工具调用不设上限一个批量调研任务可能瞬间发出 20 个请求把下游 API 直接打爆。我用信号量实现了一个简单的限流器挂在工具注册表上。每个工具可以单独配置并发上限比如 web_search 只允许 3 个并发code_executor 只允许 1 个并发。超过上限的调用进等待队列有空位再执行。让我举一个参数配置的例子# Orkas 工具限流配置示例 tools: - name: web_search max_concurrency: 3 timeout_seconds: 15 - name: code_executor max_concurrency: 1 timeout_seconds: 60这个配置被证明非常有效。以前一个并行调研任务经常把搜索 API 打到限流甚至封禁现在并发 3 路的搜索请求既够用又稳定。对了限流的信号量实现看起来简单但有一个很微妙的坑如果持有信号量的任务被挂起进入 waiting 状态信号量不会被释放会导致后续任务全部阻塞。我在实现里必须把工具调用状态的信号量生命周期和 Agent 挂起事件联动起来挂起时自动释放恢复时重新申请。5.3 错误传播链的规范化旧版 Orkas 里工具一旦报错要么吞掉返回空结果要么直接抛异常杀死整个 Agent 任务。这两种极端都不能接受。新内核的处理策略是三层工具内部的瞬时错误网络抖动、超时由限流器自动重试最多 2 次。无法重试的业务错误参数错误、权限不足封装为结构化错误对象返回给 Agent让模型自行判断如何处理。超过重试次数仍失败的升级为一次tool_failure事件编排引擎根据全局策略决定是跳过、换工具还是终止任务。这套策略让工具错误从“致命伤”变成了“可处理信号”。用户看到的 Agent 行为不再是“突然中断”而是“调用失败后自动换个思路继续执行”。5.4 MCP 适配的兼容策略Agent 生态里 MCP 协议的热度现在不用多说。Orkas 重构时我直接把 MCP 做成了工具层的“一等公民”。具体做法是写了一个 MCP 客户端适配器连接任意 MCP Server把 MCP Server 暴露的工具列表自动导入 Orkas 的工具注册表。导入时自动完成两件事一是把 MCP 工具的描述和 input schema 转换成统一的 BaseTool 格式二是从注册表继承限流和超时配置。这里有一个关键的兼容性设计MCP Server 有的是本地进程启动的有的是远程 HTTP 服务的。适配器必须同时支持两种传输。本地进程用 StdioServerTransport远程服务用 StreamableHTTPServerTransport封装在同一个接口后面。最开始我只支持本地进程结果线上部署环境是容器进程管理起来特别痛苦后来补了远程 HTTP 支持才解决。MCP 适配做好之后Orkas 的能力扩展速度明显提升。以前接一个新工具要写一段适配代码现在只要对方提供一个 MCP Server 地址或者进程启动命令配置十分钟就能上线。6. 迁移实录与踩坑复盘6.1 老 API 兼容层的“二八法则”重构内核之后最现实的问题就是老 API 怎么办。我的原则是不做百分百兼容那会让新内核重新背上旧包袱。我统计了一下线上调用频次按“二八法则”只兼容调用量最高的那部分 API。旧版的Agent.run()、Agent.stop()、Memory.append()这些核心接口新内核直接提供同样签名而一些冷门的内部接口则统一废弃通过适配层返回明确的升级提示。用户视角上旧系统和新系统就像是同一个人换了一套新的神经系统在外面看着还是这个人但内部处理速度快了几个数量级。这个平滑体验很重要因为大多数用户并不关心你内部用了什么架构他们只关心自己的代码还能不能跑。6.2 数据迁移会话历史的清洗迁移中最麻烦的不是代码是数据。旧版 Orkas 的会话历史全部是“原始消息列表”没有摘要、没有事实抽取直接丢到新系统的记忆体系里肯定会出问题。我做了一次批量数据清洗对每个历史会话重新跑一遍摘要抽取生成中期记忆和永久记忆的初始数据。这个清洗过程本身也消耗了不少模型调用 token但长期看是值得的——旧数据如果不清洗迁移后新的记忆机制面对一堆未经处理的历史效果会大打折扣。清洗有一个意外收获我发现旧系统里积累了 20 多万条会话其中有意义的长期事实只有几千条绝大多数都是无效闲聊。这个数据进一步证明了旧记忆架构的混乱程度。6.3 灰度发布的三步走重构这种事最忌讳一把梭全量上线。我采用的三步走策略已经被验证过多次具体是第一步影子流量。把线上真实请求复制一份打到新集群处理结果和旧集群做比对不返回给真实用户。这一步可以产出准确的兼容性和性能对比数据。第二步少量真实流量。拿 5% 的请求切到新系统密切关注核心指标任务完成率、平均耗时、token 消耗、报错率。有任何指标恶化立即回滚。第三步逐步扩容。5% 稳定跑一周无误后提到 25%再一周后 50%最后全量。实测下来影子流量阶段救了我一次。我发现在影子模式下新系统的任务完成率比旧系统低了 2%定位后发现问题出在记忆摘要的触发条件太保守很多场景没触发压缩上下文还是偏大。调整阈值后才恢复正常。6.4 踩坑记录四个让印象深刻的坑第一个坑是事件总线消息乱序。同一个 Agent 收到的两条事件可能因为异步处理机制改变顺序。排查了很久最后在事件上增加序列号消费端强制按序处理才解决。任何事件驱动系统不要在架构上假设“同一来源的事件一定按顺序到达”。第二个坑是记忆并发写入的锁竞争。多个 Agent 同时往向量库写入时如果库的写入线程不安全就会出现数据覆盖。最后我给记忆管理器加了分段锁不同 Agent 的数据分布在独立的分片空间互不干扰。第三个坑是状态机卡死。某个 Agent 从tool_calling迁移到waiting时如果工具结果已经返回但事件还没投递Agent 会永远停留在waiting。修复方式就是在状态机的每个等待状态都设置超时超时后调度器强制做一次“状态救助”。所以这套顶层设计中的看门狗机制其实也是从坑里爬出来的。第四个坑是 MCP 长连接超时。远程 MCP Server 网络抖动时连接会中断但适配器缓存里仍然认为连接是好的导致工具调用全部失败。后来加了一个心跳探测机制每 30 秒探测一次连接健康度断开自动重连问题解决。7. 重构后的一些真实感触Orkas 底层重构这件事前后花了三个多月线上事故清零任务完成率从 91% 提升到 98.6%平均任务耗时下降 40%token 成本下降 30%。这些数字我都觉得值但更深刻的是对这个领域本身的理解。Agent 框架的底层重构最难的不是某个算法也不是某一项技术选型而是“克制”。重构真正考验的是你有没有能力辨别哪些是要更新的哪些是即使难看但用户已经赖以生存的。我见过太多团队搞重构第一步就是把所有代码删了重写最后新系统跑不起来老系统也回不去。Orkas 这一仗我们从头到尾都守着“换心脏不换骨架”的原则每一步都让新旧系统可以并行运行、平滑切换最后才能在一个合理的节奏里完成整个地基替换。如果你也在做类似的 Agent 底座重构我只送你一句话先用一个真实事故把重构的正当性钉死再把边界画清楚然后所有技术问题都只是执行问题。重构不是技术狂欢它是一笔要算清投资回报率的工程账。