最近大半年我把开源社区里的 Agent 相关项目从里到外翻了一遍一个很强烈的感觉是热闹是真热闹同质化也是真同质化。Agent 开源项目看上去五花八门但如果剥掉 README 里那些花哨的架构图90% 的项目其实只在五层里打转——框架层、编排层、工具层、记忆层、评估层。这篇推到“Agent 解剖室”的第一篇就是我的观察笔记给准备自己造轮子、或者想从开源项目里挑一个来改的人提供一套快速定位的参照系。先说清楚这篇文章适合谁想入坑 Agent 开发但不知道从哪下手的新手在开源列表里挑花了眼的选型者以及那些纠结“要不要自己写一套框架”的团队负责人。我会尽量少讲抽象概念多用代码目录、依赖清单、README 示例这些看得见摸得着的东西来判断一个项目到底属于哪一层。1. 为什么是“五层”不是“五个赛道”我刚开始也习惯按应用场景分类比如客服 Agent、编程 Agent、数据分析 Agent、个人助理 Agent。这么分有一个问题场景是表层每个场景背后用的技术模块高度重叠。你去看一个“AI 客服”和一个“AI 文档助手”它们的核心代码很可能都包含模型调用、工具调用、上下文存储、流程编排区别只是 prompt 和接入的数据源不同。所以我换了个维度按技术分工来拆。大多数 Agent 项目打开源码你都能找到这五层里至少一层的影子框架层负责模型接入、Agent 主循环、消息收发、插件机制。这是整个 Agent 的底座。编排层负责任务拆解、步骤流转、状态管理、分支和恢复逻辑。说白了就是“下一步该干什么”。工具层负责让 Agent 能查天气、调数据库、操作办公软件、发邮件。没有这一层Agent 只是个聊天机器人。记忆层负责短期上下文、长期知识存储、向量检索、记忆更新。解决的是“Agent 记不住事”的问题。评估与可观测层负责跑测试集、记录日志、追踪调用链、判断输出质量。这一层在开源项目里最少但生产环境下最要命。这五层不是严格互斥的。很多开源项目其实是“框架层 编排层 工具层”的组合体尤其是一些端到端的 Agent 应用。但我观察下来一个项目真正花力气、有差异化贡献的地方往往只有一层。其他层只是拿现成方案拼起来的。把视角从“赛道”切换到“楼层”之后开源生态的布局就清晰了大量项目在抢同一个楼层尤其是框架层和工具层。表面上项目数量爆炸实际上大家都在解决类似的问题只是换了一层皮。后面我会逐层拆开讲。2. 逐层解剖五层分别在解决什么问题2.1 框架层所有 Agent 项目的地基也是最容易扎堆的一层框架层是整个 Agent 项目里最底层的骨架。它的核心职责很明确连接大模型 API维护一个 Agent 主循环处理用户输入和 Agent 输出之间的来回交互然后把工具、记忆、编排这些模块以某种插件机制挂进来。“Agent 主循环”这个词听起来高大上其实你可以把它理解成一个 while 循环拿到用户问题交给模型模型决定要不要调工具调完工具再把结果交回给模型直到模型觉得任务完成。框架层做的就是把这个循环抽象成可复用的代码让上层的人不用每次从零写一遍。市面上的框架层开源项目数量最多但同质化也最明显。仔细观察源码你会发现几乎所有框架都有这几个模块一个负责和大模型 API 通信的 client一个负责维护会话状态的 session 对象一个负责管理工具注册的工具管理器还有一个负责把触发的节点串起来的事件总线。名字可能叫 engine、core、runtime但功能大差不差。我在给一个团队做技术选型的时候他们列了三个框架候选三个的 README 都写着“轻量”“可扩展”“支持多模型”。最后看代码其中两个的目录结构几乎是从同一篇设计文档里长出来的。这其实不是坏事说明大家已经验证出了一套相对稳定的架构范式。但如果你打算在这个楼层自己造一个开源框架除非你在某一点上做到极致否则很难让人记住。框架层选型的建议不要光看 star 数量重点看三件事。第一主循环是否支持流式输出和中断恢复这决定生产环境能不能用第二插件接口是否稳定接口变来变去的框架维护成本极高第三是否有真实的业务案例跑在前面没有案例的框架基本还在自嗨。2.2 编排层任务怎么拆、状态怎么流转是 Agent 和 ChatBot 的分水岭编排层解决的是“复杂任务怎么一步步完成”的问题。早期 Agent 大多是线性链条先理解意图再调用一个工具把结果拼进 prompt完成任务。但真实业务里一个任务往往要拆成多个步骤有的步骤要并行有的步骤要依赖前一步的结果有的步骤失败之后要换一条路重试。所以编排层开源项目的核心资产就是一套状态流转机制。我在代码里看到最多的是两类实现一类是基于规则的状态机适合步骤比较固定的流程另一类是基于图结构的编排引擎节点之间用边来表示依赖关系每个节点是一个可执行的单元适合需要动态规划的场景。为什么 90% 的开源项目都会踩进这一层因为 ReAct 这类“思考-行动-观察”的循环模式太好实现了随便一个循环加几个 if else 就能跑通演示。但生产级的编排远不止循环你要处理循环上限、超时、节点级别的重试、状态持久化、人工审批加塞。这些才是真正考验功力的地方也是大量项目止步于 demo 的瓶颈。我见过一个开源编排引擎demo 里能把五步任务跑得很漂亮但一旦某个工具接口超时整个状态就卡死没有恢复机制。作者在 issue 里回复“重新启动一次就行”。这就是典型的把编排做得太薄。你如果要用开源编排方案一定先问三个问题节点失败能否单独重试整个任务状态能否序列化保存人工介入能否在任意节点插入2.3 工具层万物皆可插但接口越来越像工具层是 Agent 能力的外延。没有工具层Agent 只能说不会做有了工具层Agent 才能真正帮你干活。开源社区里工具层的项目通常表现为两种形态一种是通用工具网关负责把各种外部 API 统一封装成语义清晰的“工具”另一种是垂直工具集比如专门操作数据库的工具包、专门处理 Office 文档的工具包。这一层最明显的趋势是接口标准化。大家慢慢发现如果每个工具都自己定义参数格式Agent 根本没法统一调度。所以过去一年工具调用协议在往统一的方向走。现在很多项目不再自己发明工具协议而是直接支持一套标准化的描述格式工具名、参数 schema、返回值结构、错误码几乎成了通用约定。工具层的同质化更严重。你去看那些聚合了几十个工具的仓库里面大部分是“调这个 API、调那个 API、把结果 JSON 解析一下”。真正有壁垒的不是笼统的“能调多少接口”而是对某个特定领域的深度理解。举个直观例子同样是一个“操作数据库”的工具幼稚的实现是把 SQL 语句直接丢给 Agent 执行成熟的做法会把表结构、索引、权限、敏感字段全部包进去再限制 Agent 只能走预设的接口。后者没在 README 里写“接入 100 个工具”但生产价值高出几个量级。我自己接开源工具项目的时候最烦的是文档说“支持自定义工具”结果要改框架源码才能加一个新的。现在我会先看它的工具注册机制是不是声明式的我只要写一个函数、加一段描述就能被框架自动发现和调用。能做到这一点的工具层项目才值得继续看下去。2.4 记忆层从向量检索到长期记忆名字好听但落地最虚记忆层是 Agent 项目里概念最混乱的一层。很多项目把自己包装成“长期记忆解决方案”源代码一打开其实就是向量数据库加 embedding 接口再包一层 CRUD。不能说它错但离真正的“记忆”差得远。要理解记忆层先要区分三个东西会话上下文、长期知识、工作记忆。会话上下文是对话窗口里那点临时信息一般靠拼 prompt 解决长期知识是 Agent 需要查阅的产品文档、企业资料库通常用向量检索做召回工作记忆则是 Agent 在执行多步任务过程中沉淀下来的中间结果、决策理由、草稿。大多数开源记忆层项目只做了“长期知识”里的向量存储和召回。一旦用户问的是“你上次不是已经帮我查过这个项目吗”它就答不上来。因为真正的记忆要解决的不只是“存进去”和“找出来”还包括记忆什么时候该写入、什么时候该更新、什么时候该遗忘以及多个信息源冲突时以谁为准。这一块极少有开源项目做得完整。判断一个记忆层项目是否值得用的标准不是它支持多少种向量数据库而是看它的召回逻辑。我一般会看三个点第一有没有相关性重排而不是简单 Top-K第二有没有记忆压缩或摘要机制能把长对话沉淀成结构化摘要第三有没有记忆的访问权限控制否则多用户场景会串数据。记性太好也是问题。有个开源项目默认把所有对话历史都永久存着不到三个月数据库就爆了而且召回时把几个月前的过期信息翻出来误导 Agent。所以记忆层不仅要想“怎么记”还要设计“怎么忘”。2.5 评估与可观测层最薄弱、最刚需也最容易被一笔带过五层里最被低估的是评估与可观测层。你去看开源 Agent 项目的 README一半在讲怎么快速开始三分之一在展示效果截图剩下零星几个愿意聊聊测试和日志。但实际部署一个 Agent 之后最痛苦的往往不是功能不够而是你不知道它为什么答错了。可观测层要解决的是“Agent 到底干了什么”。一个多步任务跑完用户只看到最终答案但中间经历了哪几次工具调用、哪一步返回了异常、哪段上下文导致方向跑偏这些信息如果看不到排查问题就像黑盒猜谜。有些项目做了一层简单的日志但只是把每步的 prompt 和输出打到文件里没有结构化的调用链问题一复杂就没法定位。评估层更薄弱。传统软件可以靠单元测试和接口测试Agent 是概率系统同一个问题问两次可能得到两个答案没法简单断言“对”或“错”。所以真正可用的评估层至少要包含三样东西一组覆盖典型场景的评测集一套打分逻辑可以基于规则、模型、人工以及评估数据的持续回流。做齐这三样的开源项目我到现在也没见到几个。为什么这一层项目少因为做评估和可观测不性感很难发好看的 demo 截图也很难讲出“我给你接入了 50 个工具”这种吸引眼球的故事。但相信我如果你打算把一个 Agent 推到真实业务里第五层的优先级应该排到最前面。如果你要参考开源项目做评估先从“最小可用评估集”开始挑 50 条真实问题给每条写清楚预期行为和误判雷区然后跑一遍看通过率。这个动作看着简单胜过你花一整天调 prompt。3. 实操技巧五分钟判断一个开源 Agent 项目在哪一层选型的时候不用把整个项目读一遍通过三个信号基本就能定位它在五层里的位置。3.1 看代码目录的命名项目顶层目录是最诚实的架构图。如果看到这样的结构core/engine/agent_loop/sessionllm_client/model_providerplugin_hub/extension大概率是个框架层项目。如果看到nodes/workflow/graph/state_machineexecutor/scheduler/retryhuman_in_the_loop这是在编排层。如果看到大量按业务域划分的文件夹比如tools/database_tools/file_tools/search_toolsconnectors/api_adapters就是工具层。看到这些memory/vector_store/embeddingstorage/migrations/retrievalsummarization/indexing就是在做记忆层。最后如果目录里有 eval/benchmark/tests/traces/metrics 这种字眼而且不是空的至少说明作者把第五层当回事了。有一点要注意很多项目会把五层目录都摆出来给人一种“全家桶”的印象。这时候不要被迷惑你要看哪一层代码量最大、提交最频繁、注释最用心。那些只有空壳的目录说明只是留了个口子。3.2 看依赖清单依赖清单比目录结构更真实因为它直接暴露了作者用了哪些底层组件。如果依赖里主要是各个大模型平台的 SDK加上一些 async 网络库说明核心工作在框架层。如果依赖里有状态管理库、工作流引擎、消息队列这是编排层的味道。如果依赖里塞满了各种 API client、数据库驱动、爬虫解析器那工具层跑不了。向量数据库客户端、embedding 库、文档解析器成堆出现基本就是记忆层项目。而如果出现测试框架、链路追踪库、数据可视化组件说明作者在评估与可观测层下了功夫。我见过一个项目README 号称“下一代 Agent 框架”结果依赖一半是 OpenAI SDK 一半是向量库连自己的 agent loop 都没有本质是把别家框架的 demo 换了个壳。依赖清单一拉原形毕露。3.3 看 README 的示例和用户呼声README 最能反映作者的目标用户。如果一个项目的示例是“用 20 行代码创建一个能对话的 Agent”它面向的是框架层用户。如果示例是“定义一个带条件分支和人工审核的工作流”这是编排层。如果示例是“把 Notion 和数据库接入你的 Agent”这是工具层。如果示例是“让 Agent 记住你和它聊过的所有内容”这是记忆层。而如果示例里有“如何运行评测集”“如何查看调用链”那这个项目大概率在认真做第五层。更直接的办法是去 issue 区看用户都在问什么。框架层项目的高频 issue 是“怎么接入新的模型”“插件怎么加载”编排层是“任务卡住了怎么恢复”“能不能支持多人协作”工具层是“某个 API 改版了”“这个连接器报错”记忆层是“为什么召回结果不准”“数据量大就超时”评估层是“怎么定义打分规则”“怎么看某个步骤的执行记录”。用户的问题比作者的愿景诚实得多。4. 常见误区与避坑实录这五层里每个楼层都有一些反复踩坑的经典套路我整理几条高发于开源选型和二次开发过程中的问题你能绕开一个是一个。4.1 误区框架越重越大越好框架层有个吊诡现象star 高的项目往往功能列表很长但真正用得顺的没几个。原因很简单Agent 框架要覆盖的场景太多了每个场景都会加自己的配置项和抽象层最后变成一个“配置地狱”你写一个最简单的 Agent 要填三十个参数出错时堆栈能拉八百行。我接过一个项目团队为了所谓“ scalability ”选了一个大而全的框架结果业务只有三个节点却要绕五层抽象。最后我做的第一件事就是去掉框架自带的“智能路由”用最朴素的 if-else 把场景串起来。不是否定大框架而是说框架的复杂度应该匹配业务复杂度。选型的时候问一句我用了它普通任务是不是反而变麻烦了如果是坚决不选。4.2 误区把编排层当成业务层很多团队直接在编排层开源项目上写业务逻辑因为编排层看起来太方便了加个节点、画条线、连一个请求一个 Agent 流程就跑通了。但问题在于编排层只是通用状态流转它不懂你的业务规则。业务里的校验、补偿、通知、权限全部要粘连在节点前后。一旦编排引擎的版本升级节点接口一变你所有业务代码都要跟着改。我建议的做法是编排层只负责“流程状态”业务逻辑单独抽成一层。节点里不要塞太多业务而是通过工具层去调领域服务。这样哪怕你把编排引擎整个换掉业务部分还能原样搬过去。4.3 误区工具层项目火得快但不代表护城河深工具层是最近最容易火的楼层因为“接入十几个工具做演示”非常出效果。但这类项目的维护成本被严重低估了你接的每个外部 API 都在变某个接口一升级工具就得跟着修第三方服务一调整费率你的工具层决策逻辑也得跟着改。很多工具类开源项目半年后就变成“接一个坏一个”的状态不是作者懒是维护成本真的压不住。所以拿工具层项目做基底的时候我会刻意把工具调用抽象成接口不让外部依赖直接散落在业务代码里。然后把外部 API 的 SDK 再包一层留出 mock 接口。这样对方接口出问题时至少不会拖垮整个 Agent 流程。4.4 误区评估层最后再做这是我在至少五个项目里见过的同一个错误先把 Agent 功能写好上线前再补评估。补评估的时候会发现没有提前定义评测集你根本不知道哪些行为是“预期内”的没有埋点你也追不出一个错误答案到底是从哪一步开始跑偏的。最后只能靠肉眼试几个例子然后硬着头皮上线。正确做法是在你准备写第一行 Agent 代码之前就先想好评测指标和日志结构。哪怕第一版只要一个简单的通过率统计也决定了你后续迭代时有没有“方向盘”。这一步不是质量保障的附加项而是 Agent 开发的必要组件。5. 我的一点判断五层之后开源 Agent 还能往哪走说了这么多“打转”但并不是说五层不重要。五层能吸引 90% 的项目恰恰说明它们是 Agent 的通用基础设施是整个生态最容易被理解的骨架。只是当一个楼层挤满类似项目的时候新项目的突破口通常不在这一层而在楼层与楼层之间的缝隙里。我比较看好的方向有三个分别对应五层覆盖不到的盲区。第一是垂直数据的闭环同样调模型、同样做编排谁能把某个行业的数据结构、术语、规则整理成 Agent 能直接用的知识底座谁的 Agent 就会明显好用一截这一层完全不靠模型能力取胜。第二是人与 Agent 的协同流程现在的开源项目默认 Agent 是独立干活的但真实场景里常常需要人审、人批、人改把“人在环上”的交互体验做好比继续堆自动化能力更贴近落地。第三是评估数据集本身的开源代码仓库可以骗人数据不会一套覆盖典型 Agent 故障模式的公开评测集价值不亚于一个好用的框架。我个人的经验是如果你不是想做一个基础设施级的开源项目就别跟风挤框架层和编排层选一个你熟悉的业务领域把工具层和记忆层做深反而更容易被别人用起来。而如果你只是想在业务里落地 Agent也别自己搭框架直接选一个经过验证的开源框架把大部分精力放在工具接入和评估集建设上性价比高得多。五层这张图不是定型图而是一张藏宝图。看懂了它你就知道该往哪里挖也知道哪些地方只是看上去热闹脚下其实没有矿。