huggingfacesmolagents：用代码思考的轻量Agent框架

huggingface/smolagents：用代码思考的轻量Agent框架

smolagents 在 GitHub 上已经拿到 27,167 Star 了。
Hugging Face 开源了这个库，用于快速构建 Agent 应用，核心逻辑仅约 1000 行代码，支持多模型接入与沙箱执行环境。

1、核心特性

smolagents 主打轻量设计，核心代码集中在 agents.py 文件中，没有冗余抽象。
它的 CodeAgent 类型直接生成 Python 代码作为动作指令，相比传统 JSON 格式的工具调用方式，任务执行步骤减少 30%，在复杂基准测试中表现更优。
库内置多维度兼容能力：

• 模型无关：支持本地 transformers、ollama 模型，也支持 OpenAI、Anthropic 等主流厂商模型，通过 LiteLLM 集成可对接超过 100 种 LLM。
• 工具无关：支持 MCP 服务器工具、LangChain 工具，甚至可以直接把 Hugging Face Hub 上的 Space 作为工具调用。
• 模态无关：支持文本、视觉、音频、视频输入，可实现网页浏览类 Agent 功能。
  同时提供 Hub 集成能力，用户可以将开发好的工具或 Agent 上传到 Hub 分享，也可以直接拉取社区贡献的组件使用。

2、快速上手

安装默认工具集版本：

pip install "smolagents[toolkit]"

基础使用示例：

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

构建好的 Agent 可以直接推送到 Hugging Face Hub 存储：

agent.push_to_hub("m-ric/my_agent")

需要调用时直接从 Hub 加载即可。

3、执行安全

代码执行 Agent 存在安全风险，smolagents 支持多种沙箱隔离方案：

• 云托管沙箱：E2B、Blaxel、Modal，配置简单，适合快速部署。
• 自托管沙箱：Docker 容器隔离，适合对数据安全要求高的场景。
• 轻量沙箱：Pyodide+Deno WebAssembly，适合浏览器或边缘环境运行。
  默认的 LocalPythonExecutor 仅做基础限制，不是安全沙箱，不能用于执行不可信代码。

4、CLI工具

库内置两个命令行工具：
smolagent 是通用 CodeAgent 入口，支持直接传入任务提示运行，也可以进入交互式模式引导用户完成 Agent 类型选择、工具配置、模型设置等步骤。
webagent 是专用网页浏览 Agent，基于 helium 实现，可直接执行网页操作类任务。

5、性能表现

官方测试数据显示，基于开源模型构建的 CodeAgent 性能可超过闭源模型。在包含多种挑战场景的基准测试中，DeepSeek-R1 搭载 CodeAgent 的表现优于部分闭源模型方案。

开源地址：https://github.com/huggingface/smolagents