深度介绍

smolagents详细介绍

🪶

极简设计：核心不到一千行

官方把「简洁」放在第一位：智能体的主要逻辑集中在 agents.py，不足一千行代码，抽象层次刻意贴近原始代码。官方同时鼓励使用者直接读源码、只取需要的部分，而不是被框架绑住。这种做法对排障和二次开发的成本更低——出问题时可以直接定位到具体几十行，而不必先理解庞大抽象层。代价是很多工程细节（重试、日志、并发）需要自行补齐，官方提供的是骨架而非成品平台。

🧑‍💻

代码智能体：动作就是 Python 代码

官方主打的是代码智能体（CodeAgent）：它在结构上类似经典的推理—行动循环，区别在于模型输出的「动作」是可以直接执行的 Python 代码片段，工具调用因此表现为普通的函数调用。官方给出的例子是：一次动作里循环调用搜索工具覆盖多个关键词。这种方式让模型能自然地表达循环、条件与变量复用，而不是把多步操作拆成一次次的工具调用往返；可读性也更好，执行日志本身就是可审阅的代码。

📉

为什么少一些步骤：官方给出的实测口径

官方称把动作写成代码「比让模型输出要调用哪个工具的字典更好」，并引用两篇论文给出量化结论：大约少 30% 的步骤，也就是少 30% 的模型调用，同时在困难基准上取得更高成绩。这一条对成本敏感的场景尤其重要，因为智能体的花费几乎与模型调用次数成正比。需要注意的是这些数字来自特定基准与提示设置，迁移到自有任务时应自行用同一套评测复测，而不是直接按比例估算收益。

🔒

沙箱执行与一句必须看的安全警告

因为要执行模型生成的代码，官方把安全放在显眼位置：推荐把智能体代码放进沙箱运行，托管方案包括 E2B、Blaxel 与 Modal，自托管可用 Docker 容器隔离。官方同时给出一句明确的警告——内置的本地 Python 执行器只做了尽力而为的限制，**不是安全边界**，不得用来运行不可信代码。这条提醒很关键：把代码执行直接放在生产主机上等于把系统权限交给模型输出，涉及外部输入的场景必须使用真正的隔离环境。

🔌

模型无关：从本地模型到各类云端服务

官方强调「支持任何模型」：本地可用 Transformers 或 Ollama 模型，云端既可走 Hugging Face 的推理提供方（可指定具体提供方与模型），也可通过 LiteLLM 接入上百个模型，还提供兼容接口的模型类（指向 Together、OpenRouter 等服务）、Azure 与 Amazon Bedrock 的专门类。对已有调用代码的团队，通常只需换一个模型类；这也意味着可以在同一套智能体逻辑上对比不同模型的成本与效果，再决定生产用哪一个。

👁

模态无关与工具无关

官方称智能体支持文本、视觉、视频甚至音频输入，文档中有专门的视觉网页浏览教程；工具来源同样开放：可以使用任何 MCP 服务器提供的工具、直接复用 LangChain 的工具，甚至把一个 Hub 上的 Space 当作工具来调用。这种「不挑来源」的设计让团队能先复用现成能力，再逐步替换为自己的实现。需要注意的是工具越多、权限越大，沙箱与人工审批的必要性也越高。

🖥

命令行入口：通用智能体与网页智能体

官方提供两条命令行命令：一条是通用的多步代码智能体命令，支持直接带提示词与参数运行，也可以不带参数进入交互模式，由向导引导选择智能体类型、工具、模型与额外依赖；另一条是专门做网页操作的命令，基于浏览器自动化库实现，可让智能体打开页面、点击元素并提取信息。命令行方式适合把智能体接入脚本与定时任务，交互模式则适合快速试用不同工具组合。

🏛

生态位置、许可与版本节奏

smolagents 由 Hugging Face 维护，以 Apache-2.0 许可开源，核验时仓库约有 2.9 万 star；官方把它与 Hub 打通，可以把智能体推送到 Hub 作为 Space 仓库共享，也可以从 Hub 拉取他人发布的工具与智能体。官方还在一个中等难度的综合基准上比较了多个模型的代码智能体表现，结论是开源模型已能与最好的闭源模型一较高下（具体数字以官方图表为准）。版本方面，发布记录中最新为 v1.26.0（2026 年 5 月 14 日），此前有 v1.24.0（2025 年 11 月）、v1.22.0（2025 年 9 月）与 v1.21.x（2025 年 7 至 8 月）。

产品特点

核心功能与独有价值

代码智能体：动作写成可执行代码

CodeAgent 的结构类似经典推理—行动循环，但模型输出的动作是可直接执行的 Python 代码片段，工具调用表现为普通函数调用，一次动作内可以完成循环与条件逻辑。

官方给出的成本口径：少约 30% 步骤

官方引用论文称把动作写成代码比输出工具调用字典少约 30% 的步骤（即少约 30% 的模型调用），并在困难基准上取得更高成绩；该结论需在自有评测集上复测。

安全边界写得明确

官方推荐使用 E2B、Blaxel、Modal 或 Docker 做沙箱隔离，并明确警告内置的本地 Python 执行器不是安全边界、不得用于运行不可信代码。

模型、模态与工具三方面都不绑定

本地模型、Hugging Face 推理提供方、LiteLLM 及兼容接口服务均可接入；输入支持文本、视觉、视频与音频；工具可来自 MCP 服务器、LangChain 或直接使用 Hub 上的 Space。

重要更新

2026-05

v1.26.0：核验时最新的版本记录

发布记录显示 v1.26.0 于 2026 年 5 月 14 日发布，是核验时点的最新版本。项目在 1.x 系列持续迭代，升级前建议结合自有评测复测智能体行为。

2025-11

v1.24.0：年末版本节点

v1.24.0 于 2025 年 11 月 17 日发布。此前的 v1.22.0（2025 年 9 月 1 日）与 v1.21.2（2025 年 8 月 11 日）显示项目在 2025 年下半年保持较稳定的发布节奏。

2025-09

v1.22.0：九月版本

v1.22.0 于 2025 年 9 月 1 日发布。结合同一时期的文档更新，该库在代码智能体、沙箱选项与工具来源方面的能力逐步补齐，具体条目以官方发布说明为准。

2025-07

v1.21.0 与 v1.21.2：仲夏两个版本

2025 年 7 月 10 日发布 v1.21.0、8 月 11 日发布 v1.21.2。项目由 Hugging Face 团队维护，采用 Apache-2.0 许可，官方在仓库中提供安全政策与贡献指南。

产品总结

smolagents 是 Hugging Face 维护的开源轻量智能体库，官方把它定义为「用代码思考的智能体的极简库」：几行代码就能跑起智能体，核心逻辑集中在不足一千行的文件里，抽象层次刻意贴近原始代码。项目以 Apache-2.0 许可开源，核验时 GitHub 仓库约有 2.9 万 star，发布记录中最新版本为 v1.26.0（2026 年 5 月 14 日），此前有 v1.24.0（2025 年 11 月）、v1.22.0（2025 年 9 月）与 v1.21.x（2025 年 7 至 8 月）。它的核心主张是「动作即代码」：代码智能体在结构上类似经典的推理—行动循环，但模型输出的动作是可直接执行的 Python 代码片段，工具调用因此表现为普通的函数调用，一次动作里可以完成循环、条件判断与变量复用。官方称这种方式比让模型输出「要调用哪个工具」的字典更好——引用论文给出的口径是约少 30% 的步骤、也就是少约 30% 的模型调用，并在困难基准上取得更高成绩；同时也保留了传统的 JSON／文本式工具调用智能体供选择。工程配套方面，官方把安全放在显眼位置：推荐使用 E2B、Blaxel、Modal 或 Docker 作为沙箱执行环境，并明确警告内置的本地 Python 执行器只提供尽力而为的限制、不是安全边界，不得用于运行不可信代码。模型侧支持本地 Transformers 与 Ollama 模型、Hugging Face 的推理提供方、LiteLLM 以及兼容接口服务、Azure 与 Amazon Bedrock；输入支持文本、视觉、视频与音频；工具可来自 MCP 服务器、LangChain 或直接使用 Hub 上的 Space。官方另提供两条命令行入口：通用的多步代码智能体命令（支持交互式向导）与基于浏览器自动化的网页智能体命令。生态上，它与 Hugging Face Hub 打通，可把智能体推送为 Space 仓库共享，也能从 Hub 拉取他人发布的工具与智能体；官方还在一个中等难度的综合基准上比较了多个模型的代码智能体表现，结论是开源模型已能与最好的闭源模型一较高下（具体数字以官方图表为准）。使用前需要注意：内置执行器不是安全边界，涉及外部输入或不可信代码的场景必须使用真正的沙箱；官方的成本与效果数字来自特定基准，迁移到自有任务应自行复测；库本身刻意保持极简，日志、重试与并发等工程细节需要自行补齐。

产品类型: 轻量智能体框架
支持平台: Python 库（pip install smo / CodeAgent（动作即代码） / ToolCallingAgent（JSON／文本 / 命令行（smolagent 与 webagent / 沙箱执行（E2B、Blaxel、Modal、Do / Hugging Face Hub（共享与拉取智能 / MCP 与 LangChain 工具来源 / 多模型提供方（本地与云端）
资费模式: Apache-2.0 许可免费开源；成本来自所选模型提供方的调用费用与沙箱服务费用。

核验信息

参考文章与数据来源

本页事实来自 smolagents 官方渠道：GitHub 仓库 README（「用代码思考」定位、简洁性与代码行数说明、代码智能体的工作方式与沙箱选项、少约 30% 步骤与更高基准成绩的口径、模型／模态／工具三方面的兼容清单、命令行入口说明、内置本地执行器非安全边界的警告、开源模型基准比较结论、Apache-2.0 许可与引用信息）与发布页版本及日期，以及官方文档站、官方发布博客与所引论文页面。star 数、版本与功能核验于 2026 年 9 月 22 日，请以官方文档与发布说明为准。

用户体验调查

smolagents介绍页面对您是否有帮助？

把智能体的动作写成 Python 代码