1. 从"能跑就行"到"想拆开看看"：一个 Agent 框架引发的折腾
第一次把 DeepSeek 开源的 Agent 框架拉下来跑通 demo 的时候，我的反应其实挺平淡的——无非就是"模型 + 工具调用 + 循环"这套东西，市面上能见到的实现没有一百也有八十。真正让我坐不住的是第二天：我想给它加一个自定义工具，本以为要翻半天源码、改核心逻辑，结果只写了一个类、注册了一下，整个流程就通了，连主循环都没碰。
这个体验上的反差，就是我决定把它拆一遍的直接原因。插件化这三个字大家都挂在嘴边，但真正做到"加功能不用动核心"的框架其实不多，大部分所谓的插件机制，本质上是"预留了几个 if-else 分支让你填"。而这个框架给我的感觉是，它把"什么是不变的、什么是可变的"这条线划得比较清楚，扩展点开在了对的位置上。
这篇内容适合两类人看：一类是正在选型 Agent 框架、想知道它的扩展机制到底靠不靠谱的开发者；另一类是已经用过、但只停留在调 API 层面，想搞清楚"为什么它加工具这么顺"的人。我会从整体架构讲到插件注册的具体机制，再到工具描述怎么影响模型决策、多轮循环怎么收敛、状态怎么管，最后聊聊我实测中踩到的几个坑。全程不吹不黑，拆到哪说到哪。
需要先说明一点：下面涉及的具体类名、方法名，我会尽量贴近它的实际设计，但不同版本可能有出入，你以自己拉到的代码为准。我更想讲清楚的是设计思路，因为思路是跨版本稳定的，API 是会变的。
2. 拆之前先想清楚：Agent 框架到底在解决什么问题
2.1 剥掉包装，Agent 的核心就三件事
很多人一上来就看目录结构，我觉得顺序反了。应该先问：一个 Agent 框架，抛开所有花哨的概念，它到底在替你干什么？我的答案是三件事。
第一件是把模型的输出变成可执行的动作。模型吐出来的是一段文本，里面可能藏着"我要调用某个工具、参数是这些"的意图，框架要负责把这段文本解析成结构化的调用请求。第二件是把动作的执行结果喂回给模型，让它基于新信息决定下一步。第三件是控制这个循环什么时候停，不能无限转下去，也不能转一轮就草草收场。
这三件事听起来简单，但每一件都有大量细节。比如第一件，模型输出格式不稳定怎么办？第二件，工具执行报错了，是直接抛给模型还是框架自己重试？第三件，怎么判断模型是真的完成了，还是在敷衍？一个框架的成熟度，基本就体现在它对这三件事的细节处理上。
2.2 为什么"插件化"是这类框架的命门
理解了上面三件事，就能明白为什么插件化这么关键。因为在这三件事里，唯一真正多变的就是"有哪些工具可用"。主循环的逻辑是相对固定的，模型调用是相对固定的，但工具集是千人千面的——做数据分析的要 SQL 工具，做运维的要命令行工具，做客服的要查订单的工具。
如果框架把工具集写死在核心代码里，那每加一个工具就要改核心，改核心就有回归风险，用的人越多、改的人越多，核心就越不敢动。反过来，如果框架把工具定义成一个标准接口，核心只认接口不认具体实现，那扩展就变成了"实现接口 + 注册"两件事，核心代码一行不用动。
这就是插件化的价值：它把变化隔离在核心之外。我拆这个框架最大的收获，就是看清楚了它是怎么做到这一点的，以及它在哪些地方为了这个目标做了取舍。
2.3 一个容易被忽略的前提：工具描述本身就是 Prompt
在往下讲之前，有个认知必须先建立起来，否则后面很多设计你会觉得"多此一举"。那就是：在 Agent 框架里，工具的定义不只是给代码看的，更是给模型看的。
你写的工具名、工具描述、参数说明，最终都会被拼进发给模型的 prompt 里。模型是根据这些文字来决定"要不要调这个工具、怎么填参数"的。所以工具描述写得好不好，直接决定了 Agent 的智商。我见过太多人工具逻辑写得漂漂亮亮，描述就一句"查询数据"，结果模型根本不知道该什么时候用它。
这个前提会贯穿后面所有章节。你会在工具注册、参数校验、错误处理这些地方反复看到它的影子——框架的很多设计，本质上都是在帮模型"更好地理解工具"。
3. 整体骨架：一次请求在框架里到底走了哪几步
3.1 主循环的四个阶段
我把一次完整的 Agent 请求拆成了四个阶段，这样讲起来清楚。接收阶段，用户输入进来，框架把它和系统提示、历史消息、工具列表拼成一个完整的请求体。推理阶段，请求发给模型，拿到模型的回复。分发阶段，判断回复里有没有工具调用意图，有的话解析出来、执行、把结果塞回消息历史。收敛阶段，判断是否继续循环，还是把最终答案返回给用户。
这四个阶段里，接收和推理是相对固定的，分发和收敛是插件化发挥主要作用的地方。分发阶段要处理"有哪些工具、怎么调"，收敛阶段要处理"什么时候停"。我拆代码的时候，重点就放在这两个阶段。
值得一提的是，这个框架把"消息历史"当成了一个贯穿始终的核心数据结构。每一轮的工具调用和结果，都是以消息的形式追加进去的，而不是单独维护一个"工具调用记录"。这个设计选择很关键，因为它意味着模型在下一轮能看到完整的上下文，包括它自己之前调了什么、拿到了什么结果。这是多轮 Agent 能"记住自己在干嘛"的基础。
3.2 消息结构：一切状态的载体
消息结构大概是这样的：每条消息有角色（系统、用户、助手、工具），有内容，助手消息里可能还挂着工具调用列表，工具消息里则带着对应的调用 ID。这个 ID 是干嘛的？是用来把"工具返回的结果"和"模型发起的调用"对应起来的。
为什么要这么设计？因为模型可能在一轮里同时发起多个工具调用，返回的时候如果不带 ID，框架就不知道哪个结果对应哪个调用。这个细节看起来小，但如果你自己实现过 Agent，就会知道这是最容易出错的地方之一——尤其是并发执行多个工具的时候。
我实测下来，这个框架在消息结构上是比较克制的，没有搞一堆自定义字段，基本贴着通用的对话消息格式来。好处是兼容性好，你换个模型供应商，消息结构不用大改；坏处是一些框架特有的元信息没地方放，只能塞进内容里或者另开字段。这是个取舍，没有绝对的对错。
3.3 为什么主循环要设计成"可中断"的
还有一个设计我一开始没太在意，后来才觉得妙：主循环是可中断的。也就是说，框架在每一轮循环之间，都留了钩子，允许外部插入逻辑，比如检查是否超时、是否达到最大轮数、是否被用户手动取消。
这个设计的意义在于，Agent 的执行时间是不可控的。模型可能一轮就答完，也可能转十几轮。如果没有中断机制，一个跑飞的任务会一直占着资源。可中断意味着框架把"循环控制权"部分交还给了调用方，这在生产环境里非常重要。
我个人的经验是，任何要上生产的 Agent，都必须有最大轮数限制和超时控制。这个框架把这两件事做成了可配置项，而不是写死，这点是加分的。
4. 插件化机制拆解：加一个工具为什么不用动核心
4.1 工具的标准接口长什么样
这是整个框架最核心的部分，我拆得最细。一个工具，本质上要实现一个标准接口，这个接口大概包含这么几个要素：工具名、工具描述、参数定义、执行方法。
工具名是模型用来引用它的标识，必须唯一，而且最好用英文、下划线分隔，因为模型对这类命名的识别更稳。工具描述是一段自然语言，告诉模型这个工具是干嘛的、什么时候该用。参数定义通常用 JSON Schema 来描述，包括每个参数的类型、是否必填、含义。执行方法就是真正的业务逻辑，接收解析好的参数，返回结果。
关键在于，核心代码只依赖这个接口，不依赖任何具体工具。主循环在分发阶段，拿到的是"一个工具列表"，它遍历这个列表，找到匹配的工具，调用它的执行方法。至于这个工具是查数据库还是发邮件，核心完全不关心。
这就是插件化的第一层：面向接口编程。听起来是老生常谈，但真正在 Agent 场景里做对不容易，因为工具的执行结果格式五花八门，有的返回字符串，有的返回对象，有的直接抛异常。框架必须定义清楚"执行方法应该返回什么"，否则核心处理不了。
4.2 注册机制：工具是怎么"挂"上去的
有了标准接口，接下来就是注册。这个框架的注册机制我印象比较深，它支持几种方式。一种是装饰器注册，你在函数上打个标记，框架启动时自动扫描收集。一种是显式注册，你手动把工具实例加到一个注册表里。还有一种是配置式注册，通过配置文件声明要加载哪些工具。
为什么要支持多种？因为使用场景不同。装饰器适合快速开发，写起来最省事；显式注册适合需要动态控制加载哪些工具的场景，比如根据用户权限决定给哪些工具；配置式适合把工具集和代码解耦，运维层面就能调整。
我实测下来最常用的是装饰器，但生产环境我更倾向显式注册，因为可控。装饰器的问题是"隐式"，你看到一段代码不一定知道它注册了什么工具，排查问题的时候要多跳几层。显式注册虽然啰嗦，但一眼就能看清这个 Agent 到底有哪些能力。
注册表本身通常是个字典结构，键是工具名，值是工具实例。查找的时候 O(1)，很快。这里有个细节：如果两个工具重名怎么办？好的框架会报错或者警告，差的框架会静默覆盖。我建议你在注册的时候加一层校验，重名直接抛异常，别等到线上才发现工具被覆盖了。
4.3 参数校验：别让模型"自由发挥"
工具注册进来之后，模型会填参数。但模型填的参数不一定合法——可能类型不对，可能漏了必填项，可能编了一个不存在的枚举值。这时候框架要做的，就是在调用执行方法之前，先按 JSON Schema 校验一遍。
这个校验环节极其重要，但很多人会忽略。我见过有人的工具直接拿模型给的参数去拼 SQL，结果模型填了个奇怪的值，直接报错甚至出安全问题。有了校验，非法参数在进入业务逻辑之前就被拦下来了，框架可以把校验错误作为工具结果返回给模型，让模型重新填。
这个"把错误返回给模型让它重试"的机制，是 Agent 框架区别于普通函数调用的关键。普通函数调用参数错了就抛异常，Agent 里参数错了应该告诉模型"你哪里错了，重新来"，因为模型有能力自我修正。我实测中，模型第一次填错参数、第二次填对的概率相当高，前提是错误信息要清晰。
所以校验报错的时候，别只返回一句"参数错误"，要具体到"参数 xxx 应该是整数，你给的是字符串"。信息越具体，模型修正得越快。
4.4 执行隔离：一个工具崩了不能拖垮全局
最后一个机制是执行隔离。工具的执行方法里可能有各种意外——网络超时、文件不存在、第三方接口挂了。如果这些异常直接往上抛，整个 Agent 循环就断了。
这个框架的处理方式是：捕获工具执行中的异常，把它转成一条工具结果消息，返回给模型。模型看到"这个工具执行失败了，原因是 xxx"，可以选择换个工具、换个参数，或者直接告诉用户失败了。这样单个工具的故障不会导致整个任务崩溃。
我踩过的一个坑就在这里。早期我自己写的工具，异常处理很随意，有的抛有的吞，结果模型收到的错误信息格式不统一，有时候能理解有时候理解不了。后来我统一了：所有工具执行失败，都返回一个结构化的错误对象，包含错误类型和错误描述。模型对这个格式的识别明显更稳定。
提示：工具执行失败时返回给模型的错误信息，本质上也是一段 prompt。写得清楚，模型就能自救；写得含糊，模型就只能瞎猜或者放弃。
5. 工具描述怎么写，模型才愿意用、用得对
5.1 描述是给模型看的"使用说明书"
前面反复强调过，工具描述会进 prompt。这一节就具体讲讲怎么写。我的经验是，把工具描述当成"给一个聪明但完全不了解你系统的同事写使用说明"——他能力很强，但不知道你的业务背景，你得把"什么时候用、怎么用、有什么坑"讲清楚。
一个合格的描述通常包含三部分：这个工具做什么、什么时候该用它、参数怎么填。第一部分一句话说清功能，第二部分说清触发场景，第三部分如果有容易混淆的参数，要额外说明。
举个例子，一个"查询订单"的工具，描述不该只写"查询订单"，而应该写"根据订单号或用户 ID 查询订单详情，当用户询问订单状态、物流信息时使用。订单号和用户 ID 至少提供一个"。这样模型就知道什么时候调、需要什么。
5.2 工具名和描述的常见反模式
我总结了几种常见的写法问题，你看看自己有没有中招。
第一种是名字太泛，比如叫process、handle、do。模型看到这种名字完全不知道是干嘛的，只能靠描述猜，命中率低。好的名字应该自解释，比如query_order_status、send_email。
第二种是描述太短，一句话带过。模型缺少判断依据，要么不用，要么乱用。我建议描述至少两句话，把场景说清楚。
第三种是多个工具功能重叠，描述又没区分开。模型面对两个都能"查信息"的工具，会随机选，结果时好时坏。解决办法是在描述里明确边界，比如"查实时数据用 A，查历史归档用 B"。
第四种是参数说明缺失。模型不知道某个参数该填什么格式，就会瞎填。尤其是日期、枚举这类有格式要求的参数，一定要在描述里给例子。
5.3 实测：描述改一版，命中率能差多少
我做过一个不太严谨但很有说服力的对比。同一个工具，第一版描述就一句话，第二版把使用场景和参数示例都补上，其他条件不变，跑同一批测试用例。结果是第二版的工具调用准确率明显更高，尤其是那些"该不该调这个工具"的边界 case，改善最明显。
这个实验让我彻底改变了对工具描述的态度。以前我觉得描述就是文档，写给自己看的；现在我把它当成 prompt 工程的一部分，是要反复打磨的。你花在描述上的时间，会直接转化成 Agent 的可靠性。
还有个技巧：如果你发现模型总是漏调某个工具，可以在描述里加一句"当用户提到 xxx 时，务必使用本工具"。这种强调句对模型有实际影响。反过来，如果某个工具总是被误调，就在描述里加限制条件，比如"仅在用户明确要求 xxx 时使用"。
6. 多轮循环与状态管理：Agent 怎么"记住"自己在干嘛
6.1 循环终止的三个条件
Agent 循环不能无限转，必须有终止条件。这个框架里我看到了三种终止方式，值得说一下。
第一种是模型主动结束。模型这一轮没有发起任何工具调用，只返回了文本，框架就认为它给出了最终答案，循环结束。这是最常见的终止方式。
第二种是达到最大轮数。框架有个配置项，限制最多循环多少轮，超了就强制结束。这是兜底，防止模型陷入死循环。
第三种是外部中断。前面提到的可中断机制，调用方可以随时喊停。
这三种要配合使用。只有第一种，遇到模型抽风会死循环；只有第二种，正常任务可能被误杀。我的建议是最大轮数设得稍微宽松一点，比如 10 到 15 轮，同时配合超时控制，双保险。
6.2 消息历史膨胀怎么办
多轮循环带来一个现实问题：消息历史越来越长。每一轮的工具调用和结果都追加进去，几轮下来 prompt 就很大了，既费 token 又可能超出模型上下文限制。
这个框架的处理比较朴素，就是把所有消息都留着。这在轮数少的时候没问题，轮数多了就要自己想办法。我实测中用过几种策略：一种是截断，只保留最近 N 轮；一种是摘要，把早期的工具结果压缩成一句话；还有一种是按需保留，只保留和当前任务相关的消息。
截断最简单但可能丢信息，摘要需要额外调一次模型，按需保留最理想但实现复杂。我的建议是先用截断，设一个合理的窗口，观察效果。如果发现模型经常"忘记"早期信息，再考虑摘要。
这里有个坑：截断的时候不能把工具调用和对应的工具结果拆开。如果保留了助手的工具调用消息，却把对应的工具结果消息截掉了，模型会看到一个"发起了调用但没有结果"的悬空状态，行为会很奇怪。截断要以"完整的调用-结果对"为单位。
6.3 状态该放框架里还是放工具里
这是个设计问题，我纠结过一阵。有些状态是框架级的，比如当前轮数、消息历史；有些状态是工具级的，比如某个工具内部的缓存、连接池。
我的结论是：框架只管和对话流程相关的状态，业务状态交给工具自己管。框架不应该知道你的工具内部有什么状态，它只负责把调用和结果串起来。工具如果需要跨调用保持状态，自己维护，但要注意线程安全和生命周期。
这个边界划清楚很重要，否则框架会越来越重，最后变成一个什么都管的大泥球。我见过一些框架，为了"方便"，把各种业务状态都塞进核心，结果核心越来越难维护，插件化也就名存实亡了。
7. 我实测中踩到的几个坑
7.1 工具返回结果太长，把上下文撑爆
第一个坑很典型。我写了个工具，返回一大段 JSON，结果几轮下来上下文就满了，模型开始报错或者行为异常。后来我改成返回精简后的关键字段，问题就解决了。
教训是：工具返回给模型的结果，不是越全越好，而是越相关越好。模型不需要知道所有细节，它只需要知道"这一步的结果是什么、下一步该干嘛"。把无关字段砍掉，既省 token 又减少干扰。
如果确实需要返回大量数据，可以考虑返回一个摘要加一个引用 ID，模型需要细节的时候再调另一个工具去取。这种"分页"思路在处理大数据时很有用。
7.2 并发工具调用时的顺序问题
第二个坑是并发。模型有时候会在一轮里同时发起多个工具调用，框架如果并发执行，返回顺序可能和调用顺序不一致。虽然每个结果都带 ID，理论上能对应上，但如果你的工具之间有依赖关系，并发就会出问题。
我的处理是：默认串行执行，除非明确知道工具之间无依赖。串行慢一点，但结果可预测。如果确实要并发，确保工具是纯函数式的，不依赖执行顺序。
这个坑的隐蔽之处在于，它不一定每次都出问题，可能十次里错一次，排查起来很痛苦。所以宁可保守一点。
7.3 模型"假装"调用了工具
第三个坑最坑。有时候模型会在文本里写"我将调用 xxx 工具"，但实际上并没有真的发起结构化调用，只是嘴上说说。框架如果只解析结构化调用，就会漏掉这种情况，导致循环提前结束，任务没完成。
解决办法是在系统提示里明确要求模型"必须通过结构化方式调用工具，不要在文本里描述调用意图"。同时框架层面可以加一层检测，如果模型文本里出现了工具名但没有结构化调用，给个警告或者强制再走一轮。
我实测下来，加了系统提示之后这种情况少了很多，但没完全消失。所以关键任务上，还是要有人工兜底或者结果校验。
7.4 错误信息格式不统一导致模型"看不懂"
第四个坑前面提过，这里再展开说。工具执行失败时，如果错误信息格式五花八门，模型的理解成本就高。我统一成{"error": true, "type": "xxx", "message": "yyy"}这种结构后，模型对错误的处理明显更稳。
还有个细节：错误信息里不要暴露敏感的内部细节，比如堆栈、文件路径。这些对模型没用，还可能泄露信息。给模型看的错误信息，应该是"人话版"的，说清楚"哪里错了、可能的原因是什么"就够了。
8. 拆完之后，我对"插件化"的新理解
拆完这个框架，我最大的感受是：插件化不是一个功能，而是一种纪律。它要求框架作者在每一个设计决策上，都问自己"这个逻辑是核心的还是可变的"。核心的留下，可变的开出去。说起来简单，做起来要在无数细节上克制。
这个框架让我印象最深的一点，是它对"扩展点"的克制。它没有搞一大堆钩子、事件、中间件，就是老老实实把工具接口定义清楚，把注册机制做顺，把循环控制留出余地。少即是多，扩展点太多反而让人不知道从哪下手。
如果你也在做类似的东西，我的建议是：先把"工具"这一个扩展点做到极致，别急着加别的。工具是 Agent 最核心的扩展维度，把这个做顺了，框架的可用性就上来了。至于记忆、规划、多 Agent 协作这些，等工具机制稳定了再说。
最后分享一个我自己的习惯：每次拆完一个框架，我都会试着用它实现一个自己的小需求，而不是只看代码。因为看代码只能看到"它设计成什么样"，动手用才能发现"它实际好不好用"。这次我给自己加了个查天气的工具，从写接口到跑通，大概二十分钟，全程没碰核心代码。这个体验本身，就是对它插件化设计最好的验证。
