本篇文章写于2025年末，各类Agent框架群雄逐鹿，普天下刀兵四起，狼烟滚滚。

笔者做Agent开发两年多以来，经历了从早期手写Agent，到发现Langchain时惊喜于其各类好用的抽象层，以及看到AutoGen、AutoGPT等框架接连问世的乱花渐欲迷人眼，再到由于文档、改动频率、设计思想等等原因而转投CamelAI、MetaGPT等新兴框架，最后到由于业务需求愈加复杂，使用框架带来的便捷已经被额外的Tokens成本、时间延迟、精细上下文管理需求冲抵到寥寥无几，以至于反而又回归了手写Agent，返璞归真了。

行文至此，想到这两年间对曾用过或熟悉的框架的理解，可能对读者会有些用，就先将他们列出来：

不过，在这两年多以来，使用各种Agent框架中总结出的工程构建心得与直觉，在现在手搓Agent的过程中的确起到了很大的帮助。其中一部分比较直观的可以总结如下：

1. 让LLM编写代码执行工具，而不是写JSON，也不是FunctionCalling。
   • 这一点已经被许多论文反复证明了，其中最有名的一篇是发布于2024年2月的Executable Code Actions Elicit Better LLM Agents。当然，现在模型的JSON能力已经远超于当时的模型，但是模型的代码能力也同样在进步。
2. 提示词并不是越多越好，但提示词写得越多能让Agent行为一致性变强。
   • 注意，一致性强不代表最终输出效果好，一致性弱也不代表效果差，一致性强只说明了Agent在多次运行时的行为（比如调用工具的顺序，解决问题的思路）不常发生变化。
3. 提示词的格式（纯文本、Markdown、XML、JSON…）在早期模型上很重要，但现在的模型已经不敏感了。
   • 这一点已经有乐于分享的xd发布了自己的验证过程：纯文本、Markdown、YAML和JSON四种提示词样式对模型输出的影响实证。可以看到，并没有哪种格式在所有类型的任务上都表现良好，甚至有时纯文本效果好于结构化语言。所以，现在的主流大模型其实已经并不关心提示词的格式，更有效的方式是能用有条理的方式描述清楚任务本身，即人要比AI先思考
4. 上下文工程非常重要。无论是上下文压缩，动作空间约束，还是工具编排，注意力管控，都是非常值得研究的点。如果要构建复杂Agent系统，解决上下文工程问题就解决了60%的难点。
   • 关于上下文工程的具体实践方式，可以参阅笔者这两篇文章：
   • Agent降本增效的利器——从Manus工程经验一探上下文工程（ContentEngineering）
   • 真正工程级别的上下文工程是什么样的？来看看 Manus 的上下文工程哲学与实践
5. 许多场景并不需要很复杂高深的RAG系统。
   • 向量化可以简化许多问题，但很多场景其实用不到向量化。如果你有一个大量数据的系统，可以尝试setup一个轻量数据库做Text2SQL，或是SQL+向量多路召回，或是分级构建召回系统。不要对RAG形成路径依赖。

在凝练出一些直觉和心得后，构建Agent会很得心应手。

不过，在今年2月，情况突然产生了变化。当时正值OpenAI的DeepResearch功能发布，各框架纷纷出品了自己对标的开源DeepResearch项目。smolagents框架应该是最早发布的那一批，他们的项目就直接叫open-deep-research。

smolagents框架在上面表格中倒数第三个。他应该是列表里最晚问世的框架了——直到2024年12月31日才被Hugging Face社区发布。
是的，你没有听错，就是那个世界最大的模型仓库Hugging Face，他们也发布了自己的Agent框架。

当时笔者正在寻找一款开源的DeepResearch项目研究+作为平替，看到smolagents的项目后就拉下来跑了一遍。效果可以说是差强人意…胜过了在他们之后出品的一些开源项目，不过距离OpenAI的还有一定距离。

但是，他们的代码怎么这么短！

于是，笔者就仔细读了读项目代码，并跑了几个smolagents官网上的demo。

在使用这款框架体验了几个教程案例后，笔者不禁感慨之前过的都是什么苦日子——smolagents的设计原则完美match上了笔者先前自己手搓Agent时的设计思路，甚至在许多方面做得更好，更通用。

过程中，笔者还尝试使用smolagents框架实现了一个最简的文字版本DeepResearch，其中逆向搜索引擎接口的工具100行，网页爬取工具20行（用了crawler4ai），agent代码30行，就这么极简，出来效果也十分不错

当时smolagents对流式输出的支持和文档支持还不完善，但即便如此，笔者也在尝试用smolagents复刻了几个老项目之后，毅然决然地投向了smolagents框架——它恰到好处，不多麻烦开发者一点，也不多帮开发者操心一点。
笔者将自己被smolagents框架打动的点总结如下：

1. 创建工具极为方便。只需要用一个@tool装饰器加在一个python函数上，就能把这个函数变成Agent能够调用的工具，而工具描述就是函数顶部的注释。这种灵活的工具定义方式可以让开发毫无心理负担地使用诸如MinerU等外部强大的解析工具，或是自己定义灵活的检索召回逻辑，而不用花时间研究框架自带的复杂工具如何使用，效果与其它解决方案孰强孰弱 （这里点名Langchain）
2. 可以0成本生成可视化Demo网页。只需要用GradioUI()类将实例化好的agent包裹起来，就能把原先只能命令行交互的Agent打包成一个网页交互界面，无论是自己Demo实验还是给产品做Demo演示，都非常方便。
   
3. 几乎所有的不引人注目但又对开发体验很关键的细节，smolagents都在背后默默帮你实现了。这些细节会在不经意间帮你节约很多精力。比如：
   • 流式输出（可以自由切换）
   • 多轮对话（是的，上面那个案例还能继续追问，历史记录会保留）
   • 保留错误步骤（在上下文工程中很重要）
   • 兼容Langchain生态工具
   • 有修复代码格式的parser（用来尝试修复LLM生成的有一点点格式瑕疵的代码）
   • …
4. 不仅使用Code as Tool设计哲学，还内置了Python解释器沙盒，同时支持本地解释器、Docker、E2B云端等等方案，兼顾便捷与安全
5. 原生支持VLM，也就是视觉模型
6. 内置的提示词十分好用（虽然有点长）

因此，从2025年中到现在，笔者将过去写的一些工具全部迁移到了smolagens生态，日常就在smolagents的基础上做开发了。一些不需要Agentic的简单任务就使用原生的OpenAI库，用兼容协议调用模型，以工作流的方式实现；需要Agentic的任务就在smolagents的基础上开发工具，调整提示词，添加逻辑。更复杂的，就二者结合，在工作流中调用Agent，或者在Agent中调用工作流。

然而，快乐的时光总是短暂的。随着上下文工程领域逐渐形成一些最佳实践，smolagents框架就很难面面俱到引入每种优化思路了，因为部分思路是互斥的。另外，保持最简的设计哲学也不允许smolagents框架中引入很复杂的处理逻辑，比如File as Memory，比如限制模型的动作空间。
但是脱离smolagents再回归自己手搓Agent也并不现实，毕竟框架提供了这么好用的基础能力。

所以，为了同时享受框架带来的便利，并实现自己希望拥有的额外基础能力，现在就有必要深入研究smolagents框架的核心代码，并对其做一些定制化开发了。

“带你深入解析smolagents框架”系列博客是笔者开的一个新坑，希望带你深入 smolagents 框架的各个核心组件，探索CodeAgent、ToolCallingAgent、基类MultiStepAgent的设计思路、二开思路，以及工具定义、记忆编排、代码沙箱等组件的深入解析，最终实现快速无痛地在其中加入定制化功能，实现自己客制化的“smol”

如果你对本系列有兴趣，欢迎留言关注~