官方信息表
| 项目 | 内容 |
|---|---|
| 项目名称 | smolagents |
| 仓库地址 | huggingface/smolagents |
| 官方文档 | huggingface.co/docs/smolagents |
| 开源协议 | Apache 2.0 |
| 最新更新 | 2026-10-06 |
| 定位 | 极简代码智能体库，首类支持 CodeAgent |
项目背景
smolagents 是 HuggingFace 推出的智能体库，核心逻辑约 1000 行代码。它主推 CodeAgent：智能体不是写动作描述，而是直接写 Python 代码来执行任务，通过沙箱安全运行。支持任意 LLM、任意 MCP 工具、HuggingFace Hub 工具分享。
核心特性
- 极简设计：核心 agent 逻辑仅约 1000 行代码，无冗余抽象
- CodeAgent 首类支持：智能体直接写 Python 代码执行，表达能力远超工具调用
- 沙箱安全执行：支持 E2B、Modal、Docker、Blaxel 沙箱
- Hub 集成：从 HuggingFace Hub 分享和拉取工具/智能体
- 模型无关：支持 OpenAI、Anthropic、Ollama、Hub 上任意模型
- 工具无关：支持 MCP server、LangChain 工具、Hub Space 作为工具
- 多模态：支持文本、视觉、视频、音频输入
环境要求
- Python 3.10+
- 可选：E2B/Modal/Docker 沙箱账号
部署步骤
pip install smolagents
最小示例：
from smolagents import CodeAgent, HfApiModel
agent = CodeAgent(tools=[], model=HfApiModel())
agent.run("帮我计算 2026 年 10 月有多少个工作日")
代码智能体原理
传统智能体让 LLM 从预定义工具列表中选择动作；CodeAgent 让 LLM 直接写 Python 代码，在沙箱里执行任意逻辑。这意味着 LLM 可以在一个动作里组合多个工具、写循环、做条件判断。smolagents 提供安全沙箱执行，并把执行结果作为观察反馈给 LLM，形成 ReAct 循环。
常见问题 FAQ
Q：CodeAgent 写的代码安全吗？ A：必须在沙箱中执行，推荐 E2B 或 Docker，不要在本地直接跑。
Q：支持本地模型吗？ A：支持，通过 Ollama 或 transformers 接入。
Q：和 OpenAI Agents SDK 比有什么区别？ A：smolagents 更轻量、更强调代码即动作，深度绑定 Hugging Face 生态。
安装要求
pip install smolagents
# 可选沙箱
pip install e2b
支持通过环境变量配置模型：
export HF_TOKEN="hf_..."
export OPENAI_API_KEY="sk-..."
更多使用示例
from smolagents import Tool, CodeAgent, HfApiModel
class AddTool(Tool):
name = "add"
description = "两个数相加"
inputs = {"a": {"type": "int"}, "b": {"type": "int"}}
output_type = "int"
def forward(self, a, b): return a + b
agent = CodeAgent(tools=[AddTool()], model=HfApiModel())
agent.run("计算 23 加 19")