企业官网建设流程全解析

1. 为什么我要花两周时间逐个拆解这六个 Agent 代码库

过去大半年，Agent 这个词被反复提及，几乎每隔几天就有一个新的开源项目冒出来，宣称自己实现了"自主规划""工具调用""多轮反思"。但真正把代码拉下来跑一遍，你会发现相当一部分项目只是把大模型的 API 包了一层循环，加了个 while 循环就叫 Agent 框架了。我花了将近两周时间，把目前社区里讨论度比较高的六个所谓"开源"Agent 代码库逐个拉下来读源码、跑 demo、改配置，目的很简单：搞清楚它们到底解决了什么问题，哪些是真功夫，哪些是包装。

这篇文章不是一篇导购，也不是一篇排行榜。我更想做的事情是，把每个代码库的核心设计思路拆开来看，告诉你它在什么场景下值得用，什么场景下纯属给自己找麻烦。如果你正在选型，或者正在自己写 Agent 框架，这些拆解应该能帮你少走一些弯路。

先说一下我评测的维度。我不会只看 star 数，也不会只看 README 写得多漂亮。我主要看四件事：任务规划的实现方式、工具调用的抽象层次、上下文管理的策略、错误恢复和重试机制。这四个维度基本决定了一个 Agent 框架能不能从 demo 走向实际可用。很多项目在第一个维度就露馅了，规划逻辑写死在 prompt 里，换个任务就崩。

另外提前说明，我评测的这些代码库，有些确实是完全开源的，有些是"开源核心 + 商业版"的模式，还有些虽然代码公开但依赖了闭源的服务端组件。我会在每一节里明确标注这一点，因为这对你能不能真正用起来影响很大。

2. 六个代码库的整体定位与选型逻辑

在逐个拆解之前，先给一个全局的定位表，方便你快速判断哪个值得花时间深入看。我把它们按核心定位分成了三类：通用任务编排型、垂直场景优化型、以及研究导向型。

这张表是我读完源码之后的总结，和它们各自 README 里的自我描述有出入。比如库B 自称是"通用 Agent 框架"，但实际上它的状态机是写死的，你很难在不改源码的情况下扩展新的对话流程。库E 虽然功能最弱，但它的代码量最少，反而最适合拿来学习 Agent 的基本结构。

选型的时候我的建议是：先明确你的任务是不是需要动态规划。如果你的任务步骤是固定的，比如"读文件→提取字段→写数据库"，那用库B 或库D 这种状态机式的框架反而更稳，因为它的行为可预测。如果你的任务需要根据中间结果决定下一步做什么，那才需要库A 或库C 这种动态规划能力。很多人一上来就选最复杂的框架，结果发现自己的任务根本用不上那些能力，反而被框架的复杂度拖累。

还有一个容易被忽略的点是依赖的模型能力。有些框架的规划逻辑高度依赖模型的长上下文和指令遵循能力，你换一个弱一点的模型，整个流程就崩了。我在测试库C 的时候就遇到这个问题，它的树搜索需要模型在每一步都给出可靠的评分，模型稍微不稳定，搜索就会跑偏。所以选型时一定要考虑你实际能用的模型是什么水平。

3. 库A：动态规划做得最扎实，但抽象层偏重

3.1 核心设计思路拆解

库A 是我这次评测里规划能力最强的一个。它的核心思路是把任务拆解成一个有向无环图，每个节点是一个子任务，节点之间的边表示依赖关系。这个图不是预先定义的，而是由模型在运行时动态生成的。具体来说，它会让模型先输出一个任务列表，然后对每个任务判断依赖关系，最后拓扑排序得到一个执行顺序。

这个设计的好处是显而易见的：对于复杂的多步骤任务，它能自动识别哪些步骤可以并行，哪些必须串行。我在测试一个"从多个数据源收集信息并汇总"的任务时，它正确地识别出三个数据源的读取可以并行，汇总步骤必须等所有读取完成。这种能力在固定流程的框架里是做不到的。

但代价是抽象层很重。你要定义一个工具，需要写一个类，继承它的 BaseTool，实现 run 方法，还要注册到工具注册表里。一个简单的 HTTP 请求工具，代码量大概在三十行左右。相比之下，库E 里定义一个工具只需要写一个字典。这个抽象层的重量在项目规模大的时候是值得的，因为类型检查和参数校验能帮你避免很多运行时错误。但如果你只是想快速验证一个想法，这个重量会让你很烦躁。

3.2 工具调用与上下文管理

库A 的工具调用抽象是我见过比较优雅的。它用装饰器来注册工具，函数的 docstring 会自动被解析成工具描述，参数类型注解会被解析成参数 schema。这意味着你写一个普通的 Python 函数，加个装饰器，它就能被 Agent 调用。这个设计减少了大量样板代码。

上下文管理方面，库A 用的是滑动窗口加摘要的策略。当对话历史超过一定长度时，它会把早期的对话压缩成摘要，保留最近几轮的完整内容。这个策略在大多数场景下够用，但我在测试一个需要回溯早期信息的任务时发现，摘要会丢失一些细节。它的摘要 prompt 写得比较通用，没有针对特定任务优化，所以压缩后的信息可能不够精确。

注意：库A 的摘要策略是全局的，你没法针对不同的工具调用设置不同的保留策略。如果你的任务里有些工具的输出特别重要，需要完整保留，那这个框架会让你很头疼。

3.3 实操中的坑与经验

我在用库A 搭一个数据处理管道的时候踩了一个坑。它的动态规划默认是"尽可能拆细"，也就是说它倾向于把任务拆成很多小步骤。这在任务复杂的时候是好事，但在任务简单的时候会导致大量的模型调用，成本和延迟都上去了。我实测一个本来三步就能完成的任务，它拆成了七步，多出来的四步都是些"确认上一步结果"之类的冗余步骤。

解决办法是在 prompt 里明确告诉它"不要过度拆解"，但这个度很难把握。我试过在系统 prompt 里加"如果任务可以在三步内完成，不要拆成更多步骤"，效果有一些，但不稳定。后来我的做法是给规划结果加一个后处理步骤，把那些明显冗余的步骤合并掉。这个后处理逻辑需要你自己写，框架本身不提供。

另一个坑是它的错误恢复机制。当一个工具调用失败时，库A 默认会重试三次，然后把这个失败信息返回给模型，让模型决定下一步。这个设计本身没问题，但它的重试是立即重试，没有退避。如果失败原因是速率限制，立即重试只会让情况更糟。我后来在工具层面自己加了退避逻辑，但这就绕过了框架的重试机制，有点别扭。

4. 库B：状态机清晰，但扩展性受限

4.1 固定状态机的利与弊

库B 的设计哲学和库A 完全相反。它不追求动态规划，而是用一个显式的状态机来定义对话流程。每个状态是一个节点，状态之间的转移由条件决定。这个设计让整个 Agent 的行为完全可预测，调试起来非常方便。你可以清楚地知道在什么情况下它会走到哪个状态。

这个设计特别适合客服、问答这类场景，因为这类场景的对话流程本来就是相对固定的。我在测试一个多轮信息收集的任务时，库B 的表现很稳定，每一步该问什么、该收集什么信息，都严格按照状态机走，不会像库A 那样有时候会跳步或者重复问。

但问题也很明显：状态机是写死在代码里的。你想加一个新的对话分支，就得改源码。虽然它提供了一些配置项，但配置能表达的逻辑很有限。我试过用它做一个稍微复杂一点的场景，需要根据用户输入动态决定下一个问题，结果发现状态机的转移条件不支持这种动态判断，只能写死在代码里。

4.2 工具调用的简化设计

库B 的工具调用设计很简单，就是一个函数映射表。你定义一个函数，然后在配置里把函数名和触发条件映射起来。这个设计的好处是上手快，坏处是缺乏类型检查。如果你的函数参数和模型输出的参数对不上，它不会给你明确的错误提示，而是直接抛一个运行时异常。

我在测试的时候遇到过一次参数类型不匹配的问题。模型输出的是一个字符串，但我的函数期望一个整数，结果直接崩了。排查了半天才发现是类型问题。后来我养成了一个习惯，在所有工具函数的入口都加一层参数校验，把字符串转成需要的类型。这个工作本来应该由框架来做，但库B 没做。

4.3 什么场景下值得用

库B 适合的场景很明确：对话流程固定、不需要动态规划、对可预测性要求高。比如一个信息收集表单，或者一个标准化的问答流程。如果你要做的任务符合这个描述，库B 会比库A 更省心，因为它的行为完全可控。

但如果你需要任何形式的动态决策，库B 就不合适了。我见过有人试图用库B 做一个研究助手，结果发现状态机根本表达不了研究过程中的那种"根据发现决定下一步查什么"的逻辑。这种场景还是得用库A 或库C。

5. 库C：树搜索很酷，但工程化程度最低

5.1 树搜索的实现原理

库C 是这次评测里最"学术"的一个。它的核心是树搜索，具体来说是在每一步生成多个候选动作，然后用模型对每个候选打分，选择分数最高的往下走。如果走到死胡同，就回溯到上一个节点换一个分支。这个思路借鉴了传统 AI 里的搜索算法，用在 Agent 上确实能提升复杂任务的完成率。

我在测试一个需要多步推理的任务时，库C 的表现明显好于其他几个。因为它会在每一步考虑多个可能性，而不是一条路走到黑。比如在一个需要先查资料再计算的任务里，它会同时考虑"先查资料"和"先估算"两条路径，然后根据中间结果决定哪条更靠谱。

但这个能力的代价是模型调用次数成倍增加。每一步生成 N 个候选，就要调用 N 次模型来打分，再加上实际执行的动作，总的调用次数是普通 Agent 的好几倍。我实测一个任务，库A 用了 8 次模型调用，库C 用了 31 次。成本差距是实实在在的。

5.2 工程化方面的不足

库C 的代码质量是这次评测里最参差不齐的。核心的搜索逻辑写得还算清晰，但周边的工程代码就比较粗糙了。比如它的日志系统基本没有，出问题的时候只能靠 print 调试。配置管理也很原始，很多参数是硬编码在代码里的，想改就得改源码。

我遇到的最大的问题是它的错误处理。当模型返回的格式不符合预期时，库C 的处理方式是直接抛异常，而不是尝试修复或降级。这在实验环境里可以接受，但在生产环境里是不可接受的。我后来在它的模型调用层外面包了一层重试和格式修复逻辑，才勉强能用。

提示：库C 更适合作为研究参考，而不是直接用于生产。如果你想学习树搜索在 Agent 里怎么实现，它的代码值得读。但如果你想直接拿来用，需要做大量的工程化改造。

5.3 评分机制的调优经验

库C 的搜索效果高度依赖评分机制的质量。默认的评分 prompt 比较通用，在很多场景下给出的分数区分度不够。我试过针对具体任务重写评分 prompt，效果提升很明显。比如在一个代码生成任务里，我把评分标准从"这个方案好不好"改成"这个方案能不能通过测试用例"，搜索的准确率提升了一大截。

这个经验其实适用于所有用模型做评分的场景：评分标准越具体，评分质量越高。通用的"好不好"这种问题，模型给出的分数往往很随机。但如果你把评分拆成几个具体的维度，比如"正确性""完整性""效率"，每个维度单独打分，最后加权，结果会稳定很多。

6. 库D：垂直场景的务实之选

6.1 模板化流程的设计取舍

库D 的定位很明确：它不做通用 Agent，而是专注于数据处理管道这个垂直场景。它的核心是一个模板化的流程引擎，你定义一个管道，管道由若干个处理步骤组成，每个步骤可以是模型调用、代码执行、或者条件判断。

这个设计的好处是开箱即用。它内置了很多数据处理常用的工具，比如 CSV 读取、JSON 解析、字段提取、格式转换。你要做一个数据清洗管道，基本上不用写什么代码，配置一下就能跑。我在测试一个从非结构化文本里提取结构化信息的任务时，库D 的完成速度比其他几个快很多，因为它的内置工具直接覆盖了这个场景。

但代价是灵活性受限。它的流程是模板化的，你很难在流程中间插入动态决策。比如你想根据上一步的提取结果决定下一步用哪个模型，这个在库D 里就很难表达。它的条件判断只支持简单的比较，不支持复杂的逻辑。

6.2 内置工具集的实际表现

库D 的内置工具集是它最大的卖点。我逐个测试了它的主要工具，整体质量不错，但有几个细节需要注意。

文本提取工具是我用得最多的，它的准确率确实比我自己写 prompt 要高。我分析了一下它的实现，发现它在 prompt 里加了大量的 few-shot 示例，而且针对不同类型的字段用了不同的提取策略。这个细节做得很好，是真正从实践中总结出来的。

但数据校验工具就比较一般了。它只提供了基本的非空检查和类型检查，复杂的业务规则还是得自己写。我后来在它的校验步骤后面加了一个自定义的代码执行步骤，用 Python 写校验逻辑，这样才满足了我的需求。

6.3 适用边界与不适用场景

库D 适合的场景是流程相对固定、以数据处理为主、对开发速度要求高的项目。比如一个定期的数据报表生成任务，或者一个批量文档处理任务。这类任务用库D 能省很多时间。

但如果你要做的是交互式的 Agent，或者需要复杂决策的任务，库D 就不合适了。它的设计初衷就不是做这个的。我见过有人试图用库D 做一个对话机器人，结果发现它的流程引擎根本不支持多轮对话的状态管理，最后只能放弃。

7. 库E：最轻量，也最适合学习

7.1 极简设计的价值

库E 是这次评测里代码量最少的一个，核心代码加起来不到五百行。它的设计极简：一个 Agent 类，一个工具注册字典，一个主循环。主循环的逻辑就是"调用模型→解析输出→执行工具→把结果拼回上下文→继续循环"，直到模型输出结束标志。

这个极简设计有两个好处。第一是容易理解，你花半个小时就能把它的源码读完，完全搞清楚 Agent 是怎么工作的。第二是容易修改，因为代码少，你想加什么功能直接改就行了，不用去理解复杂的抽象层。

我在测试的时候，用它搭了一个简单的文件处理 Agent，从读代码到跑通只用了不到一个小时。这个速度在其他几个框架上是不可能的，光是理解它们的抽象层就得花半天。

7.2 功能缺失与补全方案

但库E 的功能缺失也很明显。它没有上下文管理，对话历史会一直增长，直到超出模型的上下文窗口。它没有错误恢复，工具调用失败就直接崩。它没有并行执行，所有工具调用都是串行的。

这些缺失在实际使用中都是问题。我后来在它的基础上自己补了几个功能。上下文管理我加了一个简单的截断逻辑，当历史超过一定长度时，丢掉最早的消息。错误恢复我加了一个 try-except，失败时把错误信息返回给模型，让它决定下一步。并行执行我没加，因为改动太大，不如直接用库A。

这些补全工作让我对 Agent 的核心机制有了更深的理解。很多时候，框架提供的那些"高级功能"，本质上就是这些基础逻辑的封装。你自己实现一遍，再去看框架的代码，会发现很多设计其实没那么神秘。

7.3 学习路径建议

如果你刚开始接触 Agent，我的建议是先从库E 开始。不要一上来就用库A 或库C 这种复杂的框架，你会被它们的抽象层淹没，搞不清楚哪些是核心逻辑，哪些是工程细节。

用库E 跑通一个最简单的 Agent，理解主循环的每一步在做什么。然后尝试加一个工具，理解工具调用的流程。再然后尝试加一个上下文管理逻辑，理解为什么需要它。这个过程走下来，你对 Agent 的理解会比直接读十篇教程都扎实。

等你把库E 玩透了，再去看库A 的源码，你会发现它的很多设计你都能理解，因为你已经自己实现过简化版了。这个学习路径是我自己走过的，确实有效。

8. 库F：多 Agent 协作的理想与现实

8.1 角色分工的设计思路

库F 是这次评测里唯一一个主打多 Agent 协作的。它的核心思路是把一个复杂任务拆给多个角色，每个角色是一个独立的 Agent，角色之间通过消息传递来协作。比如一个"研究员"角色负责收集信息，一个"分析师"角色负责分析，一个"写手"角色负责输出。

这个设计在概念上很吸引人，因为它模拟了人类团队的协作方式。我在测试一个需要多角度分析的任务时，库F 确实展现出了单 Agent 不具备的能力：不同角色会从不同角度看待问题，最后汇总的结果比单 Agent 更全面。

但实际用起来，问题也不少。最大的问题是角色之间的协调成本很高。消息传递需要定义格式，角色之间的依赖关系需要管理，一个角色卡住了整个流程就卡住了。我在测试的时候遇到过一次"研究员"角色陷入了循环，一直在收集信息不输出结果，导致后面的角色全部等待。这个问题的排查花了我不少时间。

8.2 消息传递机制的实现细节

库F 的消息传递用的是发布订阅模式。每个角色可以订阅自己关心的消息类型，收到消息后触发相应的处理逻辑。这个设计本身是合理的，但它的实现有几个细节需要注意。

消息的格式是自定义的，你需要为每种消息类型定义一个 schema。这个 schema 定义得好不好，直接影响角色之间能不能正确通信。我一开始定义的 schema 太宽松，导致角色之间经常出现理解偏差。后来我把 schema 收紧，明确了每个字段的类型和含义，通信质量才上来。

另一个细节是消息的持久化。库F 默认把消息存在内存里，进程重启就丢了。如果你的任务需要长时间运行，这个设计就有问题。我后来把消息存储换成了文件存储，虽然性能差一些，但至少不会丢数据。

8.3 多 Agent 是否值得

这是我在评测完库F 之后一直在想的问题：多 Agent 协作到底值不值得。从理论上讲，多 Agent 能处理更复杂的任务，因为每个 Agent 可以专注于自己的领域。但从实践上看，多 Agent 带来的协调成本、调试难度、以及不确定性，往往超过了它带来的收益。

我的看法是，多 Agent 适合的场景很有限。它适合那种任务可以清晰分解、角色之间依赖关系简单、对结果全面性要求高的场景。比如一个需要从多个专业角度分析的研究任务。但对于大多数任务，单 Agent 加多个工具就够了，没必要引入多 Agent 的复杂度。

如果你确实要用多 Agent，我的建议是先从两个角色开始，跑通了再增加。不要一上来就设计五六个角色，那样你根本搞不清楚问题出在哪个环节。另外，角色之间的通信协议一定要定义清楚，这是多 Agent 系统能不能稳定运行的关键。

9. 六个代码库的横向对比与选型建议

9.1 关键维度对比

把六个代码库放在一起对比，差异就很明显了。我整理了一个对比表，从几个关键维度来打分。分数是我根据实测体验给的，满分五分。

从这张表能看出来，没有哪个代码库在所有维度上都强。库A 规划强但上手难，库D 工程化好但灵活性差，库E 上手容易但功能弱。选型的时候你得根据自己的实际需求来权衡。

9.2 不同场景的推荐组合

根据我的实测经验，不同场景下的推荐是这样的：

• 快速原型验证：库E。代码少，改起来快，适合验证想法。
• 数据处理管道：库D。内置工具多，开箱即用。
• 复杂任务编排：库A。动态规划能力强，适合多步骤任务。
• 固定对话流程：库B。状态机清晰，行为可预测。
• 研究实验：库C。树搜索实现完整，适合做算法实验。
• 多角色协作：库F。但要做好协调成本高的心理准备。

还有一个组合用法值得提一下：用库E 做原型，验证通过后用库A 重写。库E 帮你快速验证想法的可行性，库A 帮你把验证过的想法工程化。这个组合我在几个项目里用过，效率比直接用库A 高。

9.3 选型时容易忽略的三个点

除了功能对比，还有三个点是我在实际使用中觉得很重要，但容易被忽略的。

第一是依赖的模型版本。有些框架的 prompt 是针对特定模型调优的，你换个模型效果会差很多。我在测试库C 的时候就发现，它的评分 prompt 在某个模型上表现很好，换一个模型就完全不行。选型的时候一定要用你实际会用的模型来测试。

第二是社区活跃度。Agent 这个领域变化很快，一个框架如果几个月不更新，很可能就落后了。我在评测的时候特意看了每个项目的最近提交时间，有几个项目的最后一次提交已经是半年前了。这种项目用起来要谨慎，遇到问题可能没人帮你解决。

第三是许可证。有些项目虽然代码开源，但许可证限制了商业使用。如果你打算用在商业项目里，一定要先看清楚许可证。我见过有人用了一个开源框架做了产品，后来发现许可证不允许商业使用，只能推倒重来。

10. 我在评测过程中踩过的坑和总结的经验

10.1 环境配置的坑

Agent 框架的环境配置比普通 Python 库要复杂，因为它们通常依赖多个外部服务。我在配置库A 的时候，光是让它能正常调用模型就花了一个多小时。问题出在它的配置加载逻辑上，它支持多种配置来源，但优先级规则写得很隐晦，我一开始把配置放错了地方，导致它一直读的是默认配置。

后来我养成了一个习惯：先把框架的配置加载逻辑读一遍，搞清楚它从哪里读配置、优先级是什么。这个工作看起来麻烦，但能帮你避免很多莫名其妙的错误。库D 的配置逻辑就清晰很多，它只有一个配置文件，所有配置都在里面，一目了然。

另一个坑是依赖版本冲突。Agent 框架通常依赖很多第三方库，这些库之间的版本兼容性有时候会有问题。我在配置库F 的时候遇到了一个依赖冲突，两个库要求同一个依赖的不同版本。解决办法是用虚拟环境隔离，但这就意味着你不能和其他项目共享环境。我现在做 Agent 相关的开发，都是每个项目一个独立的虚拟环境。

10.2 调试技巧

Agent 的调试比普通程序难，因为它的行为有很大的不确定性。同一个输入，两次运行可能得到不同的结果。这给调试带来了很大的挑战。

我的做法是把每一步的输入输出都记录下来。具体来说，我会在模型调用层和工具调用层各加一个日志，记录每次调用的输入、输出、耗时。这样当结果不符合预期时，我可以回溯每一步，看看是哪一步出了问题。

这个做法在调试库C 的时候特别有用。它的树搜索会生成很多分支，如果不记录每一步的输入输出，根本搞不清楚它为什么选了某个分支。我后来把它的搜索过程可视化了一下，把每个节点的分数和选择路径画出来，问题就一目了然了。

还有一个技巧是用固定的随机种子。虽然模型调用本身有随机性，但很多框架内部的随机逻辑是可以用种子固定的。固定种子之后，至少框架内部的行为是可复现的，这能帮你排除掉一部分不确定性。

10.3 成本控制的经验

Agent 的成本比普通模型调用高很多，因为一个任务往往需要多次模型调用。我在测试期间，六个框架加起来花了不少钱。后来我总结了几条成本控制的经验。

第一是用小模型做测试。在验证流程是否跑通的时候，用便宜的小模型，等流程没问题了再换成大模型。这个做法能省很多钱，因为流程调试阶段的调用次数是最多的。

第二是设置调用上限。给每个任务设置一个最大调用次数，超过就终止。这个能防止 Agent 陷入循环，无限调用模型。我在库C 上就遇到过这种情况，它的搜索没有深度限制，如果不设上限，它会一直搜下去。

第三是缓存重复调用。有些任务里会有重复的模型调用，比如同样的 prompt 调了两次。加一个缓存层，把结果存起来，第二次直接读缓存。这个在批量处理任务里效果很明显，能省不少调用。

10.4 对"开源"二字的重新认识

这次评测让我对"开源"这个词有了新的认识。六个代码库里，真正完全开源、可以自由使用和修改的，其实只有三个。另外三个要么是"开源核心 + 商业版"，要么依赖了闭源的服务端组件。

这个现象在 Agent 领域很普遍，因为 Agent 框架的商业价值比较高，很多团队不愿意完全开源。我的建议是，选型的时候一定要看清楚开源的范围。如果核心的规划逻辑是闭源的，那你用起来就会受制于人，想改也改不了。

另外，开源不等于免费。有些开源项目虽然代码免费，但依赖的服务是收费的。比如有些框架依赖了特定的向量数据库或者模型服务，这些服务是要花钱的。算成本的时候要把这些算进去。

11. 如果你要自己写一个 Agent 框架，我会建议这样做

11.1 从最小可用版本开始

看完这六个框架，我最大的感受是：大部分框架都过度设计了。它们在一开始就试图支持各种场景，结果抽象层做得很重，反而增加了使用难度。

如果让我自己写一个 Agent 框架，我会从最小可用版本开始。核心就是一个主循环：调用模型、解析输出、执行工具、拼回上下文。这个循环大概五十行代码就能写完。然后根据实际需求逐步添加功能，需要上下文管理就加上下文管理，需要错误恢复就加错误恢复。不要一开始就把所有功能都加上。

这个思路的好处是，你添加的每个功能都是被实际需求驱动的，而不是凭空想象的。这样框架的复杂度会控制在一个合理的范围内，不会变成一个大而全但难用的东西。

11.2 工具抽象的设计原则

工具抽象是 Agent 框架的核心，设计好坏直接影响使用体验。我的原则是让定义工具尽可能简单。理想情况下，写一个普通函数，加个装饰器，就能变成工具。库A 在这点上做得不错，它的装饰器方案很优雅。

但简单不等于没有约束。工具的参数校验、返回值格式、错误处理，这些还是要有明确的规范。我的做法是在装饰器里做参数校验，把校验逻辑封装起来，让工具函数的作者不用关心这些。这样既保持了简单，又保证了规范。

另一个原则是工具的粒度要适中。太细的工具会导致调用次数过多，太粗的工具会导致灵活性不够。我的经验是，一个工具应该完成一个完整的、有意义的操作。比如"读取文件"是一个合适的粒度，"读取文件的前十个字节"就太细了，"处理整个目录的文件"就太粗了。

11.3 上下文管理的实用策略

上下文管理是 Agent 框架里最容易被低估的部分。很多框架在这块做得很粗糙，导致 Agent 在长任务里表现不稳定。

我的策略是分层管理。把上下文分成几层：系统 prompt 层、任务描述层、工具结果层、对话历史层。每一层有不同的保留策略。系统 prompt 和任务描述始终保留，工具结果根据重要性决定保留多久，对话历史用滑动窗口加摘要。

这个分层策略比单一的滑动窗口要复杂一些，但效果明显更好。我在库A 的基础上试过这个策略，长任务的完成率提升了不少。关键是要给每一层定义清楚的保留规则，不要让它们互相干扰。

11.4 错误恢复的底线设计

错误恢复是 Agent 从 demo 走向可用的关键。我的底线设计是任何一步失败都不能导致整个任务崩溃。具体来说，模型调用失败要重试，工具调用失败要捕获异常并返回错误信息，解析失败要尝试修复或降级。

重试要有退避策略，不能立即重试。我的做法是第一次失败等一秒，第二次等两秒，第三次等四秒，最多重试三次。这个策略在遇到速率限制的时候特别有用。

错误信息要返回给模型，让模型决定下一步。但错误信息要简洁明了，不要把整个堆栈都塞进去。我的做法是把错误类型和简要描述返回给模型，详细的堆栈记在日志里。这样模型能理解发生了什么，又不会被无关信息干扰。

12. 最后分享几个实际使用中的小技巧

第一个技巧是给 Agent 设置一个"思考预算"。在 prompt 里明确告诉它，你有多少次模型调用可以用，让它自己规划怎么用。这个技巧能有效防止 Agent 陷入无意义的循环。我在库A 上试过这个做法，它会把简单的任务用少量调用完成，把复杂的任务用更多调用，分配得比较合理。

第二个技巧是用结构化输出代替自由文本。让模型输出 JSON 格式的结果，比让它输出自由文本要稳定得多。解析 JSON 比解析自然语言容易，出错率也低。库D 在这点上做得很好，它的所有工具调用都是结构化的，所以稳定性明显好于其他几个。

第三个技巧是定期检查 Agent 的行为日志。Agent 的行为有时候会出乎你的意料，定期看看日志，能发现一些潜在的问题。我在检查日志的时候发现过好几次 Agent 在做一些我没让它做的事情，比如偷偷调用了不该调用的工具。这些问题如果不看日志，很难发现。

第四个技巧是给重要的工具调用加确认机制。对于那些有副作用的操作，比如写文件、发请求，加一个确认步骤，让模型先输出它打算做什么，确认无误后再执行。这个机制能避免很多误操作。我在库B 上加了类似的功能，效果不错。

这些技巧都是我在实际使用中总结出来的，不是什么高深的理论，但确实能帮你少踩一些坑。Agent 这个领域还在快速变化，今天好用的框架明天可能就被新的替代了。保持学习，保持实践，比死守某个框架更重要。