从年初接手 Orkas 的维护到现在，我最大的感受就是：一个 Agent 项目能跑起来不难，但想让它稳定地扛住真实业务，地基必须得扎实。Orkas 是我们团队内部一套面向多智能体编排与执行的框架，最早是几个人用脚本拼出来的原型，后来逐步加了工具调用、短期记忆、并发调度，功能是越堆越多，可代码结构越来越像一座违章建筑。这次我们花了将近两个月做了一次彻底的底层重构，把执行内核、编排模型和资源管理层全部推倒重来。这篇文章不聊口号，只讲我在这次重构里踩过的坑、做过的取舍，以及那些日常文档里很少写清楚的细节。
如果你正在做 Agent 开发，或者你手里有一套已经跑起来但越改越难受的框架，这篇内容应该能帮上忙。我会从为什么必须重写说起，再把分层设计、编排模型、工具接入、并发与安全的落地方式拆开讲，最后附上重构期间最典型的一批问题和排查思路。
1. 为什么要重写地基：老架构的失控现场
1.1 从单体脚本到“三不管地带”
Orkas 最早的设计非常简单：一个Agent类，内部循环里维护一个消息列表，每次迭代把用户输入和历史消息拼进 prompt，调用大模型接口，解析返回结果，如果是工具调用就走工具函数。这套逻辑在 demo 阶段很爽，半小时就能跑通一个 agent。但等我们开始往里面加多 Agent 协作、持久化记忆、流式输出、权限校验之后，问题就暴露了。
最典型的情况是状态管理。老架构里每个 Agent 实例自己维护一份messages列表，而协作场景中 A 要把上下文传给 B，就会发生多个实例共同修改同一份列表的尴尬操作。有人用浅拷贝，有人直接传引用，结果就是同一个 user message 在不同 Agent 里被重复追加，模型上下文被无意义的信息塞满，token 成本直接翻倍。工具调用的返回结果也经常漏挂到正确的消息序列里，模型经常陷入“调用了工具但看不到结果”的幻觉循环。
这个阶段我把它叫作“三不管地带”：谁都可以写状态，谁都不为状态负责，出了问题只能靠反复看日志猜测。代码里到处都是临时补丁，今天为超时加个 sleep，明天为字段缺失加个默认值。每次有新需求进来，光是在调用链里找到该改的位置就要花半天。
1.2 并发场景像拆炸弹
真正逼我们下决心重写的，是一次线上并发压测。业务方要求同一时刻最多跑 50 个 Agent 会话，每个会话可能派生 3~5 个子 Agent。老架构在单会话下勉强能跑，一旦并发上来就开始暴露连环问题：全局唯一的工具注册表被并发写坏、模型客户端连接池被耗尽、共享内存字典里出现错乱的 session 归属。
更麻烦的是错误处理。老代码里大量使用try...except包裹整段执行逻辑，一个子 Agent 超时就会把整个链路上抛。后来实测发现，很多报错根本不是模型的问题，而是我们自己的状态没清理干净。比如一次任务结束后缓存里的中间结果没删除，下一次任务带着脏数据继续跑，输出质量明显劣化，但表面上看哪一环都是正常的。这类问题最难排查，因为你无法通过单步调试复现，只能从日志里一点点往回找。
说白了，老架构的核心问题不是某个 bug，而是它没有一个清晰的执行边界。谁在编排、谁在执行、谁在保管状态，这三件事纠缠在一起，导致任何局部修改都可能引发全局震荡。重构的第一目标就是把这三件事切开。
1.3 重写的边界：全部推翻还是保留局部
做重写决策时，团队里有个争论：是一口气全换，还是保留一部分能用的模块。我的观点是，要分三层看。模型调用、prompt 模板、少量稳定的工具函数，这些属于“资源层”，可以保留并标准化接口；编排逻辑、状态流转、并发调度，这些属于“控制层”，必须重写；外部依赖如向量库、Redis、消息队列，这些是基础设施，不涉及重构但需要重新梳理接缝。
这个判断的核心原则是：重构不是炫技，而是把走不通的路重新修直。凡是老代码里已经被多个业务方依赖、且行为稳定的部分，保留下来能大幅降低回归风险；凡是每天都让人觉得别扭、改一处崩三处的部分，别犹豫，直接推倒。
2. 新地基的三大设计判断
2.1 三层分离：编排、执行、资源的边界
新架构里我们把系统拆成三层：控制层（Orchestration）、执行层（Execution）、资源层（Resource）。
控制层只负责“决策”：下一步该选哪个 Agent、当前任务要不要拆解、子任务之间的依赖关系是什么。控制层不直接调用大模型，也不直接读写业务状态，它只产生指令，比如“调用 Agent B 处理数据分析子任务”。
执行层负责“干活”：接收控制层的指令，加载对应 Agent 的配置，组装 prompt，调用模型，执行工具函数，把结果按统一格式写回。执行层不关心高层决策，它只保证一件事——给定输入和工具环境，稳定地产出结构化结果。
资源层负责“提供能力”：模型客户端、工具注册中心、记忆存储、文件系统、外部服务连接，全都收归资源层管理。资源层对上层暴露的是接口，而不是具体对象。比如工具注册中心暴露register_tool和invoke_tool，上层不直接 import 某个工具的类。
这套分层带来的直接好处是：我们可以在不触碰编排逻辑的情况下，替换底层的模型供应商；也可以在不动执行层的前提下，增加一种新的编排策略。每个层的职责在代码审查时一眼就能看出是否越界，团队的协作效率提升非常明显。
2.2 统一消息契约：一切皆 Event
老架构里最痛苦的就是消息格式不统一。同一个任务上下文，在 A 模块里是个dict，在 B 模块里被包了一层对象，到 C 模块又变成 JSON 字符串。为了兼容，到处都在做格式转换，一转换就出错。
新架构强制规定了两种标准消息：UserMessage和AgentMessage，所有模块之间只允许传递这两种类型。AgentMessage带上了role、content、tool_calls、tool_results、metadata这些字段，metadata 里可以挂 trace_id、session_id、创建时间、来源节点。
这个设计我把“一切皆 Event”作为原则，就是每个 Agent 的执行生命周期都会对外发布事件：任务开始、模型请求发出、工具调用中、工具返回、任务完成、任务失败。所有下游系统——日志、监控、审计、缓存失效——都通过订阅事件来响应，而不是轮询状态。这样做的好处是执行链路完全可观测，任何一个卡点都能从事件流里定位。
2.3 状态管理：内存分级与持久化边界
Agent 的状态管理是这次重构里最容易翻车的地方。我们最终采用了三级记忆模型：工作记忆（当前任务上下文，放内存）、会话记忆（同一用户会话的摘要与关键事实，放 Redis）、长期记忆（跨会话的领域知识与用户偏好，放向量库）。
关键取舍在于“什么进工作记忆、什么进会话记忆”。我们的规则是：原始对话消息只留在工作记忆里，当上下文长度超过阈值时，用模型做一次摘要，把摘要和关键的实体、决策点写入会话记忆，原始消息降级为可丢弃。这样既保证了模型上下文的质量，又不会因为无限堆消息导致 token 爆炸。
状态持久化的边界也很重要。凡是能从事件流重建的状态，不持久化；只有跨会话必须保留的事实类信息，才写入 Redis 或向量库。这个原则让我们避免了“什么都要存、什么都存不对”的窘境。
3. 核心环节的落地实现
3.1 编排引擎：用有限状态机替代自由脚本
老架构的编排逻辑是“自由脚本”式的——在代码里直接写if ... then Agent A else Agent B。业务一复杂，脚本就成了面条代码。新架构把编排转成了有限状态机（FSM），每个 Agent 的执行流程被定义为一系列状态：PENDING、PLANNING、EXECUTING、WAITING_TOOL、COMPLETED、FAILED。
每个状态对应一个处理器，状态的迁移由事件触发。比如收到ToolResultReceived事件，WAITING_TOOL状态的 Agent 自动回到EXECUTING。这样做最大的价值是超时和重试变得极其自然：任何状态都可以配置最大停留时长，超时就触发Timeout事件进入FAILED，或者根据策略重试。
我特别推荐用状态机去建模 Agent 的长链条执行。人肉写几十个if分支的“思维链编排”，维护起来太痛苦了。状态机让每个执行阶段的边界变得明确，也方便了可视化监控——线上可以直接看到每个 Agent 现在卡在哪个状态。
3.2 工具注册中心与 MCP 接入
工具调用是 Agent 项目的命门。老架构里工具就是一个函数，Agent 直接调用。新架构把工具抽象成了三层：定义层（描述工具的名称、参数 schema、用途说明）、注册层（工具的管理与检索）、执行层（参数校验、调用、超时、重试、结果格式化）。
参数校验这一步特别容易被忽略。我们遇到过模型生成的工具参数里带空字符串、参数类型错误、缺少必填字段等问题。新架构统一用 JSON Schema 校验入参，不合格就返回结构化错误信息，并把它作为 tool_result 反馈给模型，让模型自行修正。实测下来，这一步能把工具调用的成功率从 78% 拉到 95% 以上。
MCP 是我们接入外部工具的主通道，也就是 Model Context Protocol。如果你还没接触过，可以把它理解成工具调用的通用协议层：远端服务把自己的工具暴露成 MCP Server，Agent 通过 MCP Client 调用。我们内部的工具注册中心把 MCP Server 注册为一个“工具组”，在 Agent 的配置里通过白名单决定暴露哪些工具组。这样外部服务接入时，不需要改动 Agent 的任何代码，只要注册一个 MCP Server 并在配置里声明即可。
3.3 并发调度与沙盒安全
并发是 Agent 落地最绕不开的话题。AI Agent 跟普通 Web 服务不一样，单个 Agent 的执行时长可能从几秒到几分钟，中间还夹杂着多次模型调用和工具调用，如果每个会话简单地占一个线程，几十个会话就能把进程打垮。
我们采用的方案是asyncio 事件循环 + 任务队列。每个 Agent 会话是一个异步任务，模型调用和工具调用都是 IO 密集操作，天然适合异步。调度器维护一个任务队列，按优先级和资源配额分发。资源配额的关键参数是“同时进行的模型请求数”和“同时进行的工具调用数”，这两个参数要独立控制，不然模型没被限流，工具调用却把下游打挂了。
安全方面，我们给工具调用加了三层防护。第一层是白名单校验：每个 Agent 只能调用配置里允许的工具，未注册的工具直接拒绝。第二层是内容过滤：工具入参和出参都要过敏感信息检测，防止用户数据落入不必要的外部服务。第三层是资源限额：每个工具调用的最大执行时间、最大输出体积、最大重试次数都有硬限制。特别要注意的是，即使内部工具也要设限额，因为模型生成的参数可能让工具陷入死循环或产生超大输出。
3.4 可观测性：每一条消息都有迹可循
重构之后我们做的第一件事，就是给所有执行过程接入全链路追踪。每个会话从创建开始就生成一个trace_id，每个子 Agent、每次模型调用、每次工具调用都挂上这个 trace_id。日志系统里可以一键检索某次任务的全部执行轨迹。
这里有个经验：日志要打印决策依据，而不是只打印结果。比如一个 Agent 决定不调用工具而是直接回答，日志里要记下“当前上下文的关键判断依据是什么、模型返回了什么信号”。这些信息对排查线上问题极其重要。因为 Agent 的行为有随机性，同一个问题两次执行可能走完全不同的路径，没有决策日志，出了问题根本无法定位。
我们还做了一个简易的执行回放面板：根据事件流把一次任务的执行过程渲染成一个时间线，哪一步耗时高、哪一步失败重试、哪一步跳过了模型调用直接走缓存，一眼就能看清。这个工具在重构后的联调阶段帮了大忙，很多问题不需要翻日志，直接看时间线就明白了。
4. 常见问题与排查技巧实录
4.1 模型陷入工具调用死循环
一个问题是被线上告警逼出来的：Agent 调用一个查询工具，工具返回“未找到数据”，Agent 又用同样的参数再调用一次，反复三次之后才放弃。原因在于工具返回的错误信息太笼统，模型无法从中学习到“应该换一种查询方式”。
解决办法有两层。第一层是工具侧：返回信息里加上改进建议，比如“当前查询条件过于严格，建议扩大时间范围”。第二层是编排侧：为同一个工具设置单轮最大调用次数，比如 3 次，超过就触发ToolOverflow事件，强制 Agent 转入反思状态，重新规划。实测下来，第二层是兜底的关键，因为指望模型每次都自觉是不现实的。
4.2 共享缓存导致上下文污染
这是重构后让我印象最深的一次故障。生产环境里两个用户同时咨询类似问题，其中一个用户的回答里出现了另一个用户的名字。排查后发现是向量存储的会话隔离出了问题：新会话在构建上下文时，取到的session_id还是旧会话的，导致把旧会话的长期记忆注入了新会话。
根因是缓存 key 的粒度太粗。修复思路很清晰：所有会话级缓存 key 必须带上 session_id 作为前缀，而且不能只在前缀上做拼接，要在读写两侧都做校验。另外，缓存里凡是涉及用户标识的字段，都要做脱敏和归属校验。现在我们的规则是：临时性数据不落缓存，必要缓存一律两段式 key（cache_key + session_id）。
4.3 工具调用超时但任务不结束
还有一个高频问题：某个外部 HTTP 工具超时了，但我们没有正确传播超时状态，导致 Agent 一直挂在WAITING_TOOL状态，直到整个任务被外部超时机制杀掉。
这个问题的技术根源很典型——我们最初用asyncio.wait配合统一的超时时间，但对不同工具有不同的合理超时窗口。比如内部数据库查询 5 秒就够了，外部报表服务却可能需要 30 秒。解决方案是让每个工具在注册时声明自己的timeout_hint，注册中心在执行时按工具维度设置超时，同时在调度器里配置一个“全局执行护栏”——单次 Agent 任务的总时长上限 150 秒，超过就会被强制中断并返回结构化错误。
4.4 排查技巧速查
| 现象 | 优先排查方向 | 常用检查手段 |
|---|---|---|
| 模型输出质量突然下降 | 上下文是否混入脏历史 | 检查 trace_id 对应的消息序列 |
| 工具调用频繁失败 | 参数校验是否漏装 | 查看注册中心参数 schema 日志 |
| 并发一高就延迟暴涨 | 模型请求限流失效 | 监控同一时刻的模型并发数 |
| 子 Agent 结果丢失 | 事件消费逻辑重复 | 检查事件流里的消费组 offset |
| 任务卡死不动 | 状态机缺少超时迁移 | 查看各状态最大停留时长配置 |
这个速查表是我们在重构后的一个月里反复修改才稳定下来的。排查 Agent 系统的问题时，我最大的体会是：不要先怀疑模型，先怀疑状态。大多数“模型变傻了”的假象，背后都是上下文被污染、工具结果没正确回传、或者缓存命中了错误的数据。
5. 重构后的数据与体验
重构上线三周后的数据，我觉得能说明一些问题。在同样的并发压力下，单任务执行耗时的 P95 从之前的 46 秒降到了 21 秒，主要原因是消除了无效的重复模型调用和排队等待。工具调用成功率从 78% 提升到 95% 左右，模型陷入循环导致的废 token 消耗下降了约 40%。最直观的改动是，以前每天能收到七八个线上异常告警，现在一周都未必有一个。
但比数据更重要的是开发体验的改善。重构之后，新接入一个外部工具的时间从半天压缩到四十分钟，因为不需要再追着代码库改动 Agent 本体，只要注册一个 MCP Server 加一条白名单配置就行。团队里新来的同事看代码的入门时间也从一周缩短到两天，分层清晰之后，新人只需要理解控制层和执行层的交互契约，就能独立接需求。
如果你也在做 Agent 相关的基础设施，我的建议是：别让“能跑”变成“只能这么跑”。当你在同一个地方完成三次补丁式修复时，就应该停下来认真考虑重构的事。重构不是对过去代码的否定，而是对系统边界的一次重新确认——知道什么该强耦合，什么该松绑定，什么该交给抽象层，什么必须暴露细节。这些判断来自于一次次线上事故和一行行日志的复盘，写不出漂亮的 PPT，但能让你的 Agent 系统真正站得住。
