1. 为什么我们要对 Agent 框架做一次底层重构做 Agent 开发的人大概都有过这种体验项目刚开始跑得挺欢工具调用、多轮对话、记忆管理都像模像样可一旦接入真实业务、工具数量上到两位数、并发请求稍微一多整个系统就开始露馅。模型调用每次都在重新初始化、工具注册表越写越乱、多智能体之间的编排逻辑散落在各个角落最后连自己都不敢改代码。Orkas 这次底层重构本质上就是被这些问题逼出来的。我先说清楚 Orkas 是什么。它是一个面向 Agent 场景的编排框架核心解决三件事模型调用的统一抽象、工具生态的注册与调度、多智能体之间的协作编排。你可以把它理解成一个Agent 的操作系统——上层是你写的业务逻辑和智能体行为下层是各种模型、工具、记忆存储Orkas 负责把这两层粘起来并且粘得足够稳、足够快、足够好扩展。这次重构不是小修小补而是把地基重新浇了一遍。原来的架构在单智能体、少量工具的场景下没问题但当我们开始处理多智能体编排、需要频繁调用本地模型、工具数量膨胀到几十个的时候旧架构的耦合问题就暴露得非常彻底。重构的目标很明确让模型调用不再重复初始化、让工具注册变成声明式、让多智能体编排从硬编码流程变成可组合的图结构。这篇文章适合谁看如果你正在从零搭一个 Agent 项目或者手里的 Agent 框架已经跑起来了但维护起来越来越痛苦再或者你在研究多智能体编排到底该怎么设计那这篇内容应该能给你不少参考。我会把重构过程中的设计取舍、踩过的坑、具体的实现细节都摊开讲尽量做到你读完能直接抄作业。2. 旧架构到底卡在哪里一次彻底的痛点复盘2.1 模型调用层的重复初始化问题旧架构最要命的问题就是模型调用的生命周期管理。当时的做法很简单每个 Agent 实例在初始化的时候自己去创建一个模型客户端。听起来没什么问题但实际跑起来是这样的——你有 10 个 Agent每个 Agent 处理请求时都要 new 一个模型客户端每个客户端背后可能还带着连接池、tokenizer、配置加载。结果就是内存里躺着一堆功能完全相同的客户端实例显存和内存被白白吃掉。更麻烦的是本地模型场景。调用本地模型不像调云端 API 那样轻量本地模型往往需要加载权重、初始化推理引擎这个过程可能耗时几秒甚至几十秒。如果每次请求都重新初始化那用户体验就是灾难性的。我实测过一个 7B 级别的本地模型冷启动加载权重需要 8 到 15 秒如果每个请求都走一遍这个流程QPS 直接掉到个位数。这个问题的本质是模型客户端的生命周期应该和 Agent 实例解耦和请求也解耦。模型客户端应该是进程级别的单例或者至少是池化的资源而不是跟着 Agent 走。旧架构没有这层抽象导致资源管理完全失控。2.2 工具注册与调度的耦合困境旧架构里工具的注册方式是命令式的——你需要在 Agent 初始化的时候手动把每个工具函数塞进一个列表里然后 Agent 在执行时遍历这个列表去匹配。工具少的时候还行工具一多就乱套了。首先是没有统一的 schema 描述每个工具的参数格式、返回值格式都不一样模型经常因为参数对不上而调用失败。其次是工具之间没有分类和优先级Agent 不知道该先调哪个后调哪个。还有一个隐藏问题工具的依赖管理。有些工具依赖数据库连接有些依赖外部 API 的密钥有些依赖本地文件系统。旧架构把这些依赖全部硬编码在 Agent 初始化逻辑里导致工具完全没法复用——你想在另一个 Agent 里用同一个工具得把依赖代码再抄一遍。2.3 多智能体编排的面条式代码多智能体编排是旧架构最混乱的部分。当时我们实现多智能体协作的方式是在一个主流程里用 if-else 和状态变量来控制——Agent A 执行完了判断条件决定要不要叫 Agent BAgent B 返回结果后再判断要不要回到 Agent A。这种写法在只有两三个 Agent 的时候还能看懂一旦 Agent 数量上去、协作路径变复杂代码就变成了意大利面条改一处牵动全身。而且这种硬编码的编排方式完全没法可视化你没法一眼看出整个协作流程长什么样调试的时候只能靠打日志一步步跟。更别说动态调整了——想加一个新的协作分支得改主流程代码风险极高。2.4 重构的核心目标清单基于上面这些痛点我们把重构目标拆成了四条模型调用统一化所有模型调用走同一套抽象接口客户端生命周期由框架统一管理支持连接池和懒加载。工具生态声明式工具通过装饰器或配置文件声明框架自动处理注册、schema 生成、依赖注入。编排图结构化多智能体协作从硬编码流程改为有向图结构节点是 Agent 或工具边是流转条件。可观测性内建每个环节都有埋点调用链、耗时、token 消耗都能追踪。这四条目标贯穿了整个重构过程后面所有的设计决策都是围绕它们展开的。3. 模型调用层的重构从重复初始化到统一资源池3.1 统一模型抽象接口的设计重构的第一步是定义一个所有模型都必须实现的抽象接口。这个接口不关心底层是云端 API 还是本地推理引擎只暴露最核心的几个方法chat对话、embed向量化、stream_chat流式对话。每个方法接收统一的请求对象返回统一的响应对象。class BaseModelClient(ABC): abstractmethod async def chat(self, request: ChatRequest) - ChatResponse: pass abstractmethod async def stream_chat(self, request: ChatRequest) - AsyncIterator[ChatChunk]: pass abstractmethod async def embed(self, texts: List[str]) - List[List[float]]: pass这样设计的好处是上层 Agent 完全不需要知道底层用的是什么模型。你今天是 OpenAI明天换成 Claude后天换成本地部署的模型只要实现了这个接口上层代码一行都不用改。这就是依赖倒置原则在 Agent 框架里的具体应用。请求对象和响应对象也做了统一。ChatRequest里包含 messages、temperature、max_tokens、tools 等字段ChatResponse里包含 content、tool_calls、usage 等字段。不同模型的差异全部在各自的 Client 实现里消化掉比如有的模型 tool_calls 格式不一样就在那个 Client 里做转换。3.2 客户端生命周期管理与连接池解决了接口统一的问题接下来就是生命周期管理。我们的方案是引入一个ModelClientManager它是进程级别的单例负责创建、缓存、复用所有模型客户端。核心逻辑是这样的每个模型客户端有一个唯一的 key这个 key 由模型名称、版本、配置参数哈希生成。当 Agent 请求一个模型客户端时Manager 先查缓存有就直接返回没有就创建并缓存。同时 Manager 还负责健康检查如果某个客户端连接断了自动重建。class ModelClientManager: _instance None _clients: Dict[str, BaseModelClient] {} def get_client(self, model_config: ModelConfig) - BaseModelClient: key self._make_key(model_config) if key not in self._clients: self._clients[key] self._create_client(model_config) return self._clients[key]对于本地模型我们还加了懒加载和预热机制。懒加载是指客户端创建时不立即加载权重等第一次真正调用时才加载。预热是指在服务启动后后台异步加载常用模型的权重这样第一个请求进来时就不用等冷启动。实测下来预热机制能把首请求延迟从 10 秒以上降到 1 秒以内。连接池这块对于云端 API 我们用的是 HTTP 连接池复用 TCP 连接减少握手开销。对于本地模型我们维护了一个推理请求队列避免并发请求把显存打爆。队列大小根据显存容量动态调整这个参数需要根据实际硬件来调没有一个通用值。3.3 流式响应与超时重试机制流式响应是 Agent 场景的刚需因为用户等不了模型把整段话生成完再显示。我们在抽象接口里就定义了stream_chat返回一个异步迭代器。不同模型的流式协议不一样有的用 SSE有的用 WebSocket有的直接返回 chunk 流这些差异都在各自的 Client 实现里处理。超时和重试机制也是必须的。我们给每个请求设置了三级超时连接超时、首字节超时、整体超时。连接超时一般设 5 秒首字节超时设 30 秒整体超时根据任务复杂度设 60 到 300 秒不等。重试策略用的是指数退避第一次重试等 1 秒第二次等 2 秒第三次等 4 秒最多重试 3 次。但要注意不是所有错误都值得重试——像参数错误、认证失败这种重试也没用只有网络抖动、限流这种才重试。提示流式响应场景下重试要特别小心因为可能已经有一部分内容输出给用户了重试会导致内容重复。我们的做法是只在首字节到达前允许重试首字节到达后如果中断就把已输出的内容作为上下文让模型接着生成。3.4 模型调用的可观测性埋点重构后我们在模型调用层加了完整的埋点每次调用都会记录模型名称、请求 token 数、响应 token 数、首字节延迟、总延迟、是否命中缓存、是否重试。这些数据汇总到监控系统可以实时看到每个模型的调用量、成功率、P95 延迟。这些数据对容量规划特别有用。比如我们发现某个模型在下午 2 点到 4 点调用量是平时的 3 倍就提前扩容了推理资源。又比如我们发现某个模型的 P95 延迟突然从 2 秒涨到 8 秒排查后发现是上游 API 限流了及时切了备用模型。4. 工具生态的重构声明式注册与依赖注入4.1 工具描述协议与 Schema 自动生成旧架构里工具的参数描述是手写的 JSON Schema容易写错还不好维护。重构后我们改成了从函数签名自动生成 Schema。你只需要用装饰器标记一个函数是工具框架会通过反射读取参数类型和注释自动生成符合模型要求的 JSON Schema。tool(namesearch_weather, description查询指定城市的天气) def search_weather(city: str, date: Optional[str] None) - WeatherResult: Args: city: 城市名称 date: 日期格式 YYYY-MM-DD默认为今天 ...框架会解析这个函数生成类似这样的 Schema{name: search_weather, parameters: {city: {type: string}, date: {type: string}}}。这样工具定义和 Schema 永远保持一致不会出现改了函数忘了改 Schema 的情况。对于复杂参数比如嵌套对象、枚举、数组我们也支持通过类型注解来表达。Python 的 typing 模块足够强大List[str]、Dict[str, int]、Literal[a, b]这些都能正确转换成 JSON Schema。4.2 工具注册表的分类与优先级工具多了之后怎么让模型快速找到合适的工具是个问题。我们的方案是给工具加分类标签比如搜索类、计算类、文件操作类、通信类。Agent 在执行时可以指定只加载某一类的工具减少模型的选择负担。优先级这块我们给每个工具设了一个 priority 字段。当多个工具都能完成同一个任务时优先调用高优先级的。比如查询天气有免费的公共 API 工具也有付费的高精度工具默认用免费的免费失败时降级到付费的。工具注册表还支持动态加载和卸载。有些工具是特定场景才需要的没必要一直挂在内存里。我们支持按需加载Agent 声明需要哪些工具框架在运行时动态注册用完可以卸载。4.3 依赖注入解决工具复用难题工具复用最大的障碍是依赖。一个数据库查询工具需要数据库连接一个 API 调用工具需要密钥这些依赖如果硬编码在工具函数里工具就没法在不同环境复用。我们引入了依赖注入容器。工具函数通过参数声明自己需要什么依赖框架在调用时自动注入。依赖的定义在配置文件里不同环境用不同配置。tool(namequery_user) def query_user(user_id: str, db: Database Depends(main_db)) - UserInfo: ...这样同一个工具函数在开发环境注入测试数据库在生产环境注入生产数据库代码完全不用改。密钥管理也是同理通过依赖注入把密钥传进去工具函数本身不接触密钥安全性也更好。4.4 工具调用的错误处理与降级策略工具调用失败是常态网络抖动、API 限流、参数错误都可能发生。我们的错误处理策略分三层第一层是工具内部的错误捕获把异常转成结构化的错误响应第二层是框架层的重试和降级根据错误类型决定是重试还是换工具第三层是 Agent 层的兜底如果所有工具都失败Agent 要能给出合理的回复而不是直接崩溃。降级策略我们配了一个工具链比如查询汇率主工具是实时 API备工具是缓存数据再备是静态汇率表。框架按顺序尝试成功就返回全失败才报错。注意工具的错误信息不要直接透传给模型因为模型的错误信息可能包含敏感内容。我们会在框架层做一次清洗只把安全的错误描述传给模型。5. 多智能体编排的重构从硬编码到图结构5.1 编排图的数据模型设计多智能体编排的核心是把协作流程抽象成有向图。图里的节点分三种Agent 节点、工具节点、条件节点。Agent 节点执行一个智能体的逻辑工具节点执行一个工具调用条件节点根据当前状态决定走哪条边。边也有类型普通边表示无条件流转条件边表示满足条件才流转并行边表示同时触发多个下游节点。整个图是一个 DAG有向无环图保证不会出现死循环。graph OrchestrationGraph() graph.add_node(planner, AgentNode(planner_agent)) graph.add_node(executor, AgentNode(executor_agent)) graph.add_node(reviewer, AgentNode(reviewer_agent)) graph.add_edge(planner, executor, conditionlambda s: s.has_plan) graph.add_edge(executor, reviewer, conditionlambda s: s.execution_done) graph.add_edge(reviewer, executor, conditionlambda s: not s.review_passed)这个图结构最大的好处是可组合。你可以把一个小图作为一个节点嵌入到大图里实现分层编排。也可以把图序列化成 JSON存到数据库里运行时动态加载这样调整编排逻辑不用改代码。5.2 状态管理与上下文传递多智能体协作的另一个难点是状态管理。Agent A 产生的中间结果Agent B 怎么拿到我们的方案是引入一个共享的OrchestrationState所有节点都能读写这个状态。状态里存的是结构化的数据不是裸字符串这样每个 Agent 都能按需取用。状态还分作用域全局状态所有节点可见局部状态只有特定子图可见。这样既能共享必要信息又能避免状态污染。状态的变更也做了版本管理每次变更记录一个快照出问题可以回滚。上下文传递这块我们做了自动裁剪。多轮协作后上下文会变得很长直接塞给模型会超 token 限制。框架会根据模型的上下文窗口大小自动保留最近的关键信息把不重要的历史压缩成摘要。5.3 并行执行与结果聚合有些任务可以并行执行比如同时查多个数据源。我们的图支持并行边一个节点执行完后可以同时触发多个下游节点这些节点并行执行全部完成后汇聚到一个聚合节点。并行执行的调度用的是异步任务队列每个并行分支是一个 task框架负责调度和等待。聚合节点会收到所有分支的结果按配置的策略合并——可以是简单拼接可以是投票也可以是让模型做总结。并行执行要注意资源竞争。如果多个分支同时调用同一个模型可能触发限流。我们在模型调用层做了并发控制同一个模型的并发请求数有上限超出的排队等待。5.4 编排过程的可视化与调试图结构的一大优势是可可视化。我们把编排图渲染成流程图每个节点的执行状态、耗时、输入输出都能在图上看到。调试的时候可以单步执行看每个节点的状态变化比打日志高效得多。我们还做了执行回放功能。每次编排执行都会记录完整的 trace包括每个节点的输入、输出、耗时、状态变更。出问题时可以回放整个执行过程精确定位是哪一步出了错。6. 重构后的实测数据与踩坑记录6.1 性能对比重构前后的关键指标重构完成后我们做了一轮压测对比数据还是挺明显的。在 50 并发、工具数量 30 个、平均每个请求触发 3 次模型调用的场景下指标重构前重构后提升平均响应延迟4.2s1.8s57%P95 延迟12.5s4.1s67%内存占用3.2GB1.1GB66%首请求延迟本地模型11s0.9s92%工具调用成功率87%98.5%11.5pp内存占用的下降主要来自模型客户端的复用原来 50 个并发就有 50 个客户端实例现在共享一个池子。首请求延迟的下降来自预热机制。工具调用成功率的提升来自 schema 自动生成和错误处理优化。6.2 踩过的坑模型客户端缓存失效重构过程中踩的最大的坑是模型客户端的缓存 key 设计。一开始我们用模型名称做 key结果发现同一个模型不同 temperature 配置的客户端被混用了导致输出不稳定。后来改成用完整配置的哈希做 key问题解决。但这个改动又引入了新问题配置里有些字段是不影响客户端行为的比如超时时间、重试次数这些字段变化不应该导致客户端重建。我们最后把配置分成两部分影响客户端创建的结构配置和影响单次调用的运行时配置只有结构配置变化才重建客户端。6.3 踩过的坑工具 schema 的边界情况Schema 自动生成也踩了坑。Python 的Optional[str]我们一开始生成的是{type: string}但模型不知道这个参数是可选的经常不传导致报错。后来改成生成{type: [string, null]}并在 description 里标注可选模型就正确理解了。还有默认值的问题。函数参数有默认值时Schema 里要带上 default 字段否则模型不知道可以不传。枚举类型要用 enum 字段列出所有可能值不然模型会瞎编。6.4 踩过的坑编排图的循环依赖编排图设计成 DAG 是为了避免死循环但实际业务里确实有需要循环的场景比如执行-评审-修改这个循环。我们的解决方案是允许受控循环边上可以设最大循环次数超过次数强制跳出。同时循环必须有退出条件否则框架会拒绝加载这个图。6.5 常见问题速查表问题现象可能原因排查方向解决方案模型调用超时客户端未复用/网络问题检查客户端缓存命中率确认 Manager 单例生效工具调用参数错误Schema 生成有误打印生成的 Schema检查类型注解和默认值编排卡死循环无退出条件查看执行 trace设置最大循环次数内存持续增长状态未清理检查状态快照定期清理历史快照并发请求被限流并发控制缺失查看模型调用并发数配置并发上限和队列7. 这套架构还能怎么扩展重构完成后我们发现这套架构的扩展性比预期好很多。模型层加新模型只需要实现一个 Client 类工具层加新工具只需要写一个带装饰器的函数编排层加新流程只需要画一张图。这种低成本的扩展能力是旧架构完全不具备的。后续我们计划在几个方向继续深化。一是记忆体系的整合把短期、长期、永久记忆统一到编排状态里让 Agent 能跨会话记住东西。二是安全防护在工具调用和模型调用之间加一层审计防止敏感操作。三是评测体系给每个 Agent 和工具建评测集改动后自动跑回归。如果你也在做 Agent 框架我的建议是尽早把模型调用和工具注册这两层的抽象做出来。这两层是地基地基不稳上层怎么搭都是危房。编排层可以晚点做但一旦 Agent 数量超过三个就一定要上结构化编排硬编码的流程撑不了多久。最后分享一个实操小技巧重构的时候不要一次性全改先做模型调用层跑通了再做工具层最后做编排层。每层改完都做一轮压测确保没有性能回退。我们当时就是分了三期做的每期间隔两周给了充分的观察期避免了一次性大改带来的风险。