把"大模型"和"动手干活"连在一起,过去总得在框架的抽象层里绕上好几圈:定义节点、配置工具描述、写状态流转……等真正跑起来,热情已经耗掉一半。

smolagents 是 Hugging Face 开源的轻量 Agent 库,核心代码约 1000 行,让大模型直接写 Python 代码来完成任务,而不是输出一堆 JSON 指令。

这个库的思路很直接:与其让模型学会一种"工具调用"的格式,不如让它用自己最擅长的语言——Python——来表达意图。2024 年底发布以来,它一直在 GitHub 上保持着相当高的热度,截至 2026 年 9 月已收获约 2.9 万 star,最新稳定版为 v1.26(2026 年 5 月发布)。

用代码思考,而不是填 JSON

传统 Agent 的做法是让大模型输出一段结构化指令,说"我要调用哪个工具、传什么参数",框架解析完再去执行。smolagents 的 CodeAgent 换了个玩法:让模型直接生成一段可运行的 Python 代码,框架负责把它跑起来,再把执行结果喂回给模型继续推理。

代码天生支持循环、条件判断、函数嵌套,一个复杂的多步任务往往一段脚本就能表达完。Hugging Face 引用的研究显示,这种"代码即行动"的方式相比传统工具调用平均能减少约 30% 的步骤和模型调用——对按调用量计费的 API 来说,这意味着同样的任务能省下不少开销。跑一个多步任务时,模型会自己写出类似下面的逻辑:

for request in ["smolagents", "code agent"]:
    print(f"{request}:", web_search(request))

而开发者要做的,只是用 @tool 装饰器把一个普通 Python 函数声明成工具,把 docstring 写清楚,Agent 就会在合适的时机自己调用它。手写胶水代码、预先编排每一步调用,这些都可以省掉。

想接哪个模型,自己说了算

smolagents 对模型保持中立,这是它设计上比较舒服的一点。模型可以是 Hugging Face Hub 上的托管推理服务,可以通过 LiteLLM 接入 OpenAI、Anthropic 等上百家厂商的接口,也可以用本地跑的 transformers 或 Ollama 模型。切换引擎往往只需换一行模型初始化代码,Agent 本身的逻辑不用动。

模型的能力直接决定了 Agent 的上限——模型越擅长写代码,CodeAgent 的表现越好,这一点在社区评测里被反复提及。如果你手里有趁手的本地开源模型,或者想控制 API 成本,都可以自由组合。

代码执行的安全边界

让模型生成并执行代码,安全是绕不开的问题。smolagents 的态度很明确:本地执行器只适合开发调试,不是安全边界;真正要跑重要任务,应该把代码丢进隔离沙箱。它提供了 E2B、Modal、Blaxel 这类云端托管沙箱,也支持自建 Docker 容器,执行环境可以在 Agent 定义时通过一个参数切换。

另外,Agent 生成代码时默认只能使用 Python 内置模块,如果确实需要 pandas、requests 这类第三方库,得通过 additional_authorized_imports 显式授权。模型写出的代码如果报错,Agent 会读取错误信息自我修正重试,步数上限由 max_steps 控制,默认 6 次。

绑在 Hugging Face 生态上

作为 Hugging Face 自家出品的库,smolagents 和 Hub 的联动是它的独有优势。做好的工具或 Agent 可以一键推到 Hub 上分享,别人也能像装依赖一样直接拉下来复用;甚至可以把一个 Gradio Space 应用整体当作一个工具交给 Agent 使用。

它能调用的工具也不局限于自家生态——任何 MCP 服务器的工具、LangChain 的工具都能接进来。文本之外,Agent 还支持视觉、视频、音频等多模态输入。不想写代码的话,内置的 smolagent 和 webagent 两条命令行命令也能快速跑起一个 Agent,后者专门用来做浏览器自动化任务。

对想入门 AI Agent 的开发者来说,smolagents 最大的价值在于"看得懂":整个核心逻辑就 1000 行左右,出了任何问题都可以直接翻源码弄明白,而不是跟层层抽象搏斗。几百行源码级别的透明感、代码即行动的效率、随意切换模型和工具的灵活性,这三样东西叠在一起,让它成了轻量 Agent 开发里一个相当顺手的起点。感兴趣的话,到官网就能看到完整文档和示例。

一句话:如果想让 AI 用代码自己干活,又不愿意被笨重的框架牵着走,smolagents 这个 1000 行的轻量库,值得你花一个下午试一遍。