插件化Agent框架源码拆解：工具、执行器、记忆与规划器四层设计

1. 拆之前先想清楚为什么要看这个 Agent 框架大模型圈子里做应用的人最近一年绕不开一个词——Agent。但真正动手写过 Agent 的人都知道从能聊天到能干活之间隔着一道巨大的鸿沟。你让模型调用一个工具它可能给你编一个不存在的函数名你让它连续执行三步任务它可能在第二步就忘了第一步的上下文你想给它加一个新能力结果发现得改核心调度逻辑牵一发动全身。我最近花了两天时间把一个开源 Agent 框架的源码从头到尾拆了一遍。这个框架的核心卖点就两个字插件化。拆完之后我的感受是它把插件化这件事做到了一个相当彻底的程度——不是那种预留了几个扩展点的伪插件化而是从工具注册、执行调度、上下文管理到多 Agent 协作每一层都是可插拔的。这篇文章适合两类人看一类是正在选型 Agent 框架、想知道插件化到底能做到什么程度的开发者另一类是自己正在写 Agent 调度逻辑、想参考一下成熟设计思路的工程师。我会从整体架构、核心模块、实操流程、踩坑经验四个维度展开尽量把每个设计决策背后的为什么讲清楚。说明本文基于对该框架公开源码的分析和实际运行测试涉及的具体项目名称和代码细节做了脱敏处理但技术逻辑和设计思路保持原样。2. 整体架构拆解插件化到底体现在哪几层2.1 从一次完整的 Agent 调用说起要看懂一个框架的插件化设计最好的方式不是先看目录结构而是先跟一遍完整的调用链路。我以一个最典型的场景为例用户说帮我查一下明天北京的天气然后根据天气推荐穿什么衣服。这个请求进入框架后大致经历以下几个阶段意图解析框架把用户输入交给大模型模型判断需要调用天气查询工具输出一个结构化的工具调用请求。工具路由框架根据模型输出的工具名称在注册表中找到对应的工具实现。参数校验与执行对模型输出的参数做校验然后执行工具函数拿到天气数据。结果回传与二次推理把天气数据塞回对话上下文再次调用模型模型根据天气数据生成穿衣建议。最终输出把模型的最终回复返回给用户。这个链路看起来简单但每一步都藏着插件化的设计空间。比如第2步的工具路由如果框架把工具名称硬编码在调度逻辑里那你每加一个工具就得改核心代码。而这个框架的做法是工具注册表本身就是一个可替换的组件你甚至可以把默认的本地注册表换成一个远程的工具市场。2.2 四层插件化架构拆完源码后我把它的插件化设计归纳为四个层次从外到内依次是层级插件化对象扩展方式典型场景第一层工具Tool实现标准接口并注册添加自定义 API 调用第二层执行器Executor替换执行策略切换同步/异步/分布式执行第三层记忆Memory替换存储后端从内存切换到向量数据库第四层规划器Planner替换推理策略从 ReAct 切换到 Plan-and-Execute这四层不是孤立的它们之间通过明确定义的接口通信。这意味着你可以在不改动其他层的前提下单独替换任意一层的实现。比如你只想把记忆后端从内存换成 Redis那只需要实现 Memory 接口然后在初始化时传入你的实现即可工具层和规划器层完全无感知。2.3 为什么是这四层而不是别的我一开始有个疑问为什么偏偏抽象出这四层后来想明白了这四层对应的是 Agent 运行时的四个核心关注点——能做什么工具、怎么执行执行器、记得什么记忆、怎么决策规划器。任何一个 Agent 系统不管用什么语言写、跑在什么环境里都逃不开这四个问题。把这四个关注点各自抽象成可替换的组件好处是显而易见的。举个实际例子你在开发环境用内存做记忆存储跑得好好的上线后发现多轮对话一多内存扛不住了这时候你只需要换一个基于数据库的 Memory 实现其他代码一行不用改。这种局部替换、全局无感的能力才是插件化真正的价值。实操心得判断一个框架的插件化是不是真插件化有个简单的测试方法——试着在不看核心源码的情况下只通过文档和接口定义替换掉其中一个组件。如果替换过程中你被迫去读调度器的内部实现那说明抽象层没做干净。3. 工具系统插件化的门面与核心3.1 一个工具从定义到被调用的完整生命周期工具系统是大多数开发者接触这个框架的第一个入口也是插件化体现得最直观的地方。我以一个自定义工具为例走一遍完整流程。假设我要添加一个查询快递物流的工具。第一步是定义工具的描述信息这部分信息会被传给大模型让模型知道这个工具的存在和用法。描述信息通常包括工具名称、功能说明、参数列表每个参数的类型、是否必填、含义。第二步是实现工具的执行逻辑。框架要求工具的执行函数接收一个参数字典返回一个字符串或结构化结果。这里有个设计细节值得注意执行函数的返回值会被框架统一序列化后塞回对话上下文所以你的返回值最好是模型能理解的格式而不是一堆二进制数据。第三步是注册。注册的方式通常有两种装饰器注册和显式注册。装饰器注册写起来更简洁适合工具数量少的场景显式注册更灵活适合需要动态决定注册哪些工具的场景。# 装饰器注册的典型写法伪代码 tool(namequery_logistics, description根据快递单号查询物流信息) def query_logistics(tracking_number: str) - str: # 实际调用物流 API result call_logistics_api(tracking_number) return format_result(result)3.2 工具描述的质量直接决定调用准确率这是我在实操中体会最深的一点。很多人写工具描述很随意写个查询天气就完事了结果模型经常在不需要的时候调用它或者调用时传错参数。工具描述本质上是给模型看的使用说明书写得越清楚模型调用越准确。我总结了几条写工具描述的经验功能说明要包含什么时候用和什么时候不用。比如当用户询问实时天气时使用此工具如果用户只是闲聊天气话题不要调用。参数说明要给出示例值。模型看到示例值后对参数格式的理解会准确很多。工具名称用动词开头保持唯一性。避免出现两个功能相似、名称也相似的工具模型会混淆。3.3 工具执行的安全边界工具执行是 Agent 与外部世界交互的窗口也是风险最集中的地方。这个框架在工具执行层做了几道防线我觉得设计得挺合理。第一道是参数校验。框架会根据工具定义中的参数类型对模型输出的参数做类型检查。如果模型输出了一个字符串但工具定义要求整数框架会在执行前拦截并返回错误信息给模型让模型重新生成。第二道是超时控制。每个工具执行都有超时限制防止某个工具卡死导致整个 Agent 流程挂起。超时时间可以全局配置也可以针对单个工具单独设置。第三道是异常隔离。工具执行过程中抛出的异常会被框架捕获转换成模型能理解的错误信息而不是直接让整个流程崩溃。这一点很重要——模型收到错误信息后往往能自己调整策略重试。注意事项如果你要添加的工具涉及敏感操作比如写数据库、发请求到外部系统建议在工具实现内部再加一层权限校验不要完全依赖框架层面的防护。框架的校验是通用的业务层面的安全需要你自己兜底。4. 执行器与调度插件化的发动机4.1 执行器的职责边界执行器是框架里最容易被忽视、但设计难度最高的部分。它的职责是接收规划器输出的执行计划按顺序或并行地调用工具处理执行过程中的各种异常最后把结果汇总返回。为什么说它设计难度高因为执行器要处理的情况太多了工具有依赖关系怎么办某个工具执行失败了要不要重试多个工具可以并行执行时怎么调度执行时间过长怎么中断这些问题没有标准答案不同的业务场景需要不同的策略。这个框架的做法是把执行器抽象成一个接口默认提供一个通用实现同时允许你替换成自己的实现。默认实现覆盖了最常见的场景——顺序执行、失败重试、超时中断。如果你的场景比较特殊比如需要分布式执行那就自己实现一个执行器。4.2 顺序执行与并行执行的取舍默认执行器采用的是顺序执行策略也就是一个工具执行完再执行下一个。这个选择乍看保守但仔细想想是合理的。顺序执行的最大好处是上下文一致性有保障。每个工具执行完后结果会立即更新到上下文中下一个工具执行时能看到最新的上下文。如果改成并行执行多个工具同时读写上下文就需要处理并发一致性问题复杂度会上升一个量级。但顺序执行也有明显的短板如果两个工具之间没有依赖关系顺序执行就是浪费时间。比如同时查天气和查汇率这两个操作完全可以并行。所以框架在执行器层面预留了并行执行的扩展点你可以根据工具之间的依赖关系动态决定哪些工具可以并行。我实测下来对于大多数对话式 Agent 场景顺序执行已经够用了。真正需要并行执行的往往是那种批量处理类的任务比如同时查询十个城市的天气。这种场景下与其在 Agent 层面做并行不如把批量查询封装成一个工具在工具内部做并行。4.3 重试策略的设计细节工具执行失败是常态尤其是调用外部 API 的时候。框架的默认重试策略是失败后重试两次每次间隔一秒。这个策略对大多数场景够用但有几个细节值得注意。首先不是所有失败都值得重试。如果失败原因是参数错误重试多少次都没用反而浪费时间和 token。框架的做法是区分错误类型网络超时类的错误会重试参数校验类的错误直接返回给模型。其次重试次数不是越多越好。重试次数太多会导致整个流程响应时间过长用户体验变差。我一般把重试次数控制在两次以内超过两次还失败就让模型换个思路。最后重试时要考虑幂等性。如果工具的操作不是幂等的比如下单这种操作重试可能会导致重复下单。这种工具应该在实现内部做好幂等控制而不是依赖框架的重试机制。5. 记忆系统插件化里的隐形功臣5.1 短期记忆与长期记忆的分工记忆系统是 Agent 框架里最容易被低估的模块。很多人觉得记忆就是把对话历史存起来但实际上记忆系统的设计直接决定了 Agent 能不能处理长对话、能不能记住用户偏好、能不能从历史经验中学习。这个框架把记忆分成了短期记忆和长期记忆两层。短期记忆存的是当前对话的上下文通常有长度限制超出限制后会做截断或摘要。长期记忆存的是跨对话的信息比如用户的偏好、历史任务的结果通常存在外部存储里。两层记忆的分工很明确短期记忆保证当前对话的连贯性长期记忆保证 Agent 的个性和经验积累。这种分层设计的好处是你可以针对不同的记忆层采用不同的存储策略和淘汰策略。5.2 记忆的写入与检索策略记忆系统最难的不是存而是什么时候存、存什么、怎么取。先说写入。不是所有对话内容都值得存入长期记忆。如果每句话都存长期记忆很快就会被噪音淹没。框架的做法是提供一个可配置的写入策略你可以选择每轮对话都写入、只在任务完成后写入或者由模型判断是否值得写入。再说检索。当 Agent 需要用到长期记忆时怎么从海量记忆中找出相关的那几条最简单的做法是按时间倒序取最近几条但这种方式在记忆量大时效果很差。更好的做法是用向量检索把记忆转成向量存起来检索时用语义相似度匹配。这个框架默认提供的是基于关键词的简单检索但预留了向量检索的扩展接口。如果你用的是支持向量检索的存储后端只需要实现对应的 Memory 接口即可。5.3 记忆压缩长对话的必修课长对话场景下上下文长度是个硬约束。模型的上下文窗口就那么大对话轮次一多早期的内容就会被挤出去。这时候就需要记忆压缩。框架提供了几种压缩策略我比较常用的是摘要压缩当对话轮次超过阈值时把最早的几轮对话交给模型做摘要用摘要替换原始对话。这样既保留了关键信息又大幅缩短了上下文长度。实操心得摘要压缩的提示词很关键。我试过几种写法最后发现效果最好的是让模型提取对话中的事实性信息和用户偏好忽略寒暄和重复内容。这样压缩后的摘要信息密度高后续对话中模型能准确回忆起关键信息。6. 规划器插件化的大脑6.1 ReAct 与 Plan-and-Execute 的适用场景规划器决定了 Agent 怎么思考。这个框架内置了两种规划策略ReAct 和 Plan-and-Execute。ReAct 的思路是边想边做模型先输出一个思考然后决定调用哪个工具拿到结果后再思考下一步。这种方式灵活适合步骤不确定的任务但缺点是容易走一步看一步缺乏全局规划。Plan-and-Execute 的思路是先规划再执行模型先制定一个完整的执行计划然后按计划逐步执行。这种方式适合步骤明确的任务执行效率高但缺点是计划一旦制定就不容易调整遇到意外情况可能卡住。我的经验是任务步骤少于三步、且步骤之间有依赖关系时用 ReAct任务步骤多、但步骤相对独立时用 Plan-and-Execute。当然也可以把两者结合先用 Plan-and-Execute 制定大框架每个步骤内部用 ReAct 灵活处理。6.2 规划器的可替换性设计规划器的插件化体现在它是一个独立的组件通过标准接口与执行器通信。规划器输出的是一个执行计划执行器不关心这个计划是怎么来的只负责执行。这种设计的好处是你可以实现自己的规划器。比如你想用某个特定的大模型做规划或者你想实现一种全新的规划策略比如基于树搜索的规划只需要实现规划器接口即可执行器和工具层完全不用改。我试过替换默认规划器实现了一个带反思的规划器每次执行完一个步骤后让模型反思一下当前进展是否符合预期如果不符合就重新规划。这个规划器在复杂任务上的表现比默认的好不少但代价是 token 消耗增加了大约 40%。6.3 规划器的提示词工程规划器的效果很大程度上取决于提示词的质量。框架默认的规划器提示词写得比较通用但在特定场景下你需要针对性地调整。我总结了几条规划器提示词的调整经验明确输出格式。规划器的输出需要被程序解析所以格式必须严格。我一般要求模型输出 JSON 格式的计划每个步骤包含步骤描述和所需工具两个字段。限制步骤数量。不加限制的话模型可能会规划出十几步的计划其中很多步骤是冗余的。我一般限制在五步以内。提供工具清单。规划器需要知道有哪些工具可用才能制定出可执行的计划。把工具清单和工具描述一起放进提示词里规划准确率会明显提升。7. 实操从零搭一个带自定义插件的 Agent7.1 环境准备与依赖安装前面讲的都是设计层面的东西这一节我带你走一遍完整的实操流程。假设我们要搭一个个人助理 Agent具备三个能力查天气、记笔记、查笔记。环境准备比较简单核心依赖就是框架本身和它依赖的大模型 SDK。我建议用虚拟环境隔离依赖避免和系统里的其他包冲突。# 创建虚拟环境 python -m venv agent_env source agent_env/bin/activate # 安装框架和模型 SDK pip install agent-framework model-sdk安装完成后先跑一个最小示例验证环境是否正常。最小示例通常就是让 Agent 回答一个简单问题不涉及工具调用。如果这一步能跑通说明基础环境没问题。7.2 定义并注册三个自定义工具接下来定义三个工具。查天气工具调用外部天气 API记笔记工具把内容写入本地文件查笔记工具从本地文件读取内容。# 查天气工具 tool(nameget_weather, description查询指定城市的实时天气。当用户询问天气时使用。) def get_weather(city: str) - str: # 调用天气 API返回格式化后的天气信息 data weather_api.query(city) return f{city}当前天气{data[condition]}温度{data[temp]}℃ # 记笔记工具 tool(namesave_note, description保存一条笔记。当用户要求记录信息时使用。) def save_note(content: str) - str: with open(notes.txt, a, encodingutf-8) as f: f.write(content \n) return 笔记已保存 # 查笔记工具 tool(namesearch_notes, description搜索已保存的笔记。当用户询问之前记录的信息时使用。) def search_notes(keyword: str) - str: with open(notes.txt, r, encodingutf-8) as f: lines f.readlines() matched [l for l in lines if keyword in l] return \n.join(matched) if matched else 没有找到相关笔记三个工具定义完后框架会自动把它们注册到工具注册表中。这里有个细节装饰器的执行顺序会影响注册顺序但一般不影响功能因为框架在路由时会根据工具名称精确匹配。7.3 配置记忆后端与规划器工具定义好后接下来配置记忆后端和规划器。开发阶段我用内存做记忆存储规划器用默认的 ReAct。# 初始化 Agent agent Agent( modelyour-model-name, memoryInMemoryMemory(max_turns20), # 保留最近20轮对话 plannerReActPlanner(), executorSequentialExecutor(max_retries2, timeout30) )这里的参数选择有讲究。max_turns20是我实测下来比较平衡的值太小了容易丢失上下文太大了会拖慢响应速度。max_retries2和timeout30也是类似都是根据实际使用体验调出来的。7.4 跑通第一个多轮任务配置完成后跑一个多轮任务测试一下。我设计的测试场景是用户帮我查一下上海的天气Agent 调用查天气工具返回天气信息用户帮我把今天的天气记下来Agent 调用记笔记工具保存天气信息用户我之前记过哪些关于天气的笔记Agent 调用查笔记工具返回匹配的笔记这个测试场景覆盖了工具调用、上下文传递、记忆检索三个核心能力。如果三步都能正确执行说明 Agent 的基本功能已经跑通了。我实测下来这个流程在默认配置下能跑通但第三步偶尔会失败——模型有时候会忘记之前查到的天气信息导致记笔记时内容不完整。解决办法是在记笔记工具的提示词里明确要求从对话历史中提取天气信息或者在规划器层面增加一步确认信息完整性的检查。8. 常见问题与排查技巧实录8.1 工具调用失败的高频原因在实操过程中工具调用失败是最常见的问题。我把遇到过的原因整理成了一张速查表问题现象可能原因排查方法解决方案模型不调用工具工具描述不清晰检查工具描述是否说明了使用场景补充什么时候用的说明调用时参数错误参数定义不明确检查参数类型和示例值在参数描述中加示例工具执行超时外部 API 响应慢查看工具执行日志增加超时时间或加重试返回结果模型看不懂返回格式不规范检查返回值是否结构化统一返回 JSON 字符串多轮对话后工具失效上下文被截断检查记忆配置增加记忆轮次或做摘要压缩这张表里的每一条都是我实际踩过的坑。其中模型不调用工具和调用时参数错误这两类问题占了所有问题的七成以上而根源基本都是工具描述写得不够清楚。8.2 上下文丢失的排查思路上下文丢失是另一个高频问题尤其是在长对话场景下。表现是Agent 在对话早期能正确使用某个信息但对话进行到十几轮后就忘记了这个信息。排查这个问题的思路是先确认记忆配置是否合理再确认上下文是否被意外截断。框架一般会提供日志记录每轮对话实际传给模型的上下文内容。把日志打出来看一眼就能知道是记忆没存进去还是存进去了但没被检索出来。如果是记忆没存进去检查写入策略如果是存进去了但没检索出来检查检索策略。我遇到过一次比较隐蔽的情况记忆存进去了检索也能检索到但检索到的记忆没有被正确拼接到提示词里。这种问题只能通过看日志发现。8.3 性能优化的几个实用技巧Agent 的性能瓶颈通常不在计算而在等待——等模型响应、等工具执行、等网络传输。优化性能的核心思路是减少等待。第一个技巧是缓存工具结果。对于查询类的工具如果同样的参数在短时间内被多次调用可以直接返回缓存结果。我实测下来这个优化能减少大约 30% 的工具调用耗时。第二个技巧是精简提示词。提示词越长模型响应越慢。把不必要的说明删掉把工具描述写精炼能明显提升响应速度。第三个技巧是并行执行无依赖的工具。前面说过默认执行器是顺序执行的但如果你的场景里有大量无依赖的工具调用可以考虑替换成并行执行器。注意事项并行执行虽然快但会带来上下文一致性问题。如果你的工具之间有隐式的依赖关系比如工具 B 依赖工具 A 写入的数据千万不要并行执行。9. 插件化设计的边界与取舍拆完这个框架我最大的感受是插件化不是越多越好而是要在灵活性和复杂度之间找到平衡点。这个框架把插件化做到了工具、执行器、记忆、规划器四个层面但并没有把提示词模板、日志系统这些也做成插件。为什么因为提示词模板和日志系统的变化频率低做成插件带来的灵活性收益抵不过增加的抽象复杂度。这给了我一个重要的启发判断一个模块该不该插件化关键看它的变化频率和变化维度。变化频率高、变化维度多的模块值得插件化变化频率低、变化维度单一的模块硬编码反而更清晰。另外插件化带来的一个隐性成本是调试难度上升。当出问题时你需要在多个插件之间来回排查而不是在一个文件里从上往下读。所以我在实际项目中会尽量控制插件的数量只在真正需要灵活替换的地方做插件化。这个框架的插件化设计我觉得最值得借鉴的一点是每个插件接口都定义得非常窄。工具接口只要求实现执行方法记忆接口只要求实现存和取方法。接口越窄实现起来越简单替换成本越低。反观有些框架插件接口定义得又宽又复杂实现一个插件要写几百行代码这种插件化就失去了意义。最后分享一个我在拆源码时用的小技巧先看接口定义文件再看默认实现最后看测试用例。接口定义告诉你能做什么默认实现告诉你怎么做测试用例告诉你怎么用。按这个顺序看理解一个陌生框架的速度会快很多。