smolagents：Hugging Face 千行代码 Agent 库｜CodeAgent 与沙箱执行指南

smolagents mascot

仓库：https://github.com/huggingface/smolagents 官方文档：https://huggingface.co/docs/smolagents 许可证：Apache-2.0 运行形态：Python 库 + CLI，无 Web 端口

1. 项目简介

smolagents 是 Hugging Face 出品的轻量 Agent 库。核心 agents.py 约 1000 行代码，主打"让 agent 用 Python 代码片段而不是 JSON 字典来做动作"——官方论文称这种 CodeAgent 方式比传统 tool-calling 少 30% 步数、在难 benchmark 上得分更高。

1.1 核心信息一览

项目	内容
仓库	huggingface/smolagents
定位	轻量、模型无关的 Python Agent 库
许可证	Apache-2.0
安装	`pip install "smolagents[toolkit]"`
核心抽象	`CodeAgent` / `ToolCallingAgent`
沙箱后端	E2B、Blaxel、Modal、Docker
模型接入	HF Inference、LiteLLM、OpenAI、Azure、Bedrock、Transformers、Ollama

1.2 适用场景

想在自己的 Python 项目里几十行代码跑起一个多步 Agent；
想用 CodeAgent 让模型直接写 Python 代码做工具调用；
想把 agent 分享到 Hugging Face Hub 作为 Space；
需要 vision / 视频 / 音频多模态输入的 agent。

1.3 能力边界（官方口径）

内置 LocalPythonExecutor 不是安全沙箱，只能做最佳努力限制，不能跑不可信代码；
生产环境请用 E2B / Blaxel / Modal / Docker 等隔离沙箱；
库本身只提供 agent 循环，不内置托管 UI（可以推到 HF Space 获得 Web UI）。

2. 功能特性

极简核心：agent 主逻辑约 1000 行，便于阅读与二次开发；
CodeAgent 一等公民：动作写成 Python 代码，工具以函数调用形式出现；
Hub 集成：agent.push_to_hub(...) 分享、Tool.from_hub(...) 拉工具；
模型无关：InferenceClientModel、LiteLLMModel、OpenAIModel、TransformersModel、AzureOpenAIModel、AmazonBedrockModel；
多模态：文本、视觉、视频、音频输入；
工具无关：MCP server、LangChain 工具、Hub Space 都能当工具；
CLI：smolagent 通用多步 agent、webagent 基于 helium 的浏览器 agent。

3. 官方界面预览

smolagents 官方 mascot

下图为不同开源 / 闭源模型在 agent benchmark 上的对比（官方 README 配图）：

benchmark

4. 官方跳转链接汇总

仓库主页：https://github.com/huggingface/smolagents
文档：https://huggingface.co/docs/smolagents/index
发布博客：https://huggingface.co/blog/smolagents
CodeAgent 参考：https://huggingface.co/docs/smolagents/reference/agents#smolagents.CodeAgent
沙箱（E2B）：https://e2b.dev/
Blaxel：https://blaxel.ai
Modal：https://modal.com/
安全策略：https://github.com/huggingface/smolagents/blob/main/SECURITY.md

5. 前置要求与服务器配置

Python 3.9+（具体以 PyPI 页面为准）；
一个模型 Provider 凭据（HF Inference Token、OpenAI、Anthropic、Azure 等任一）；
生产环境需要 E2B / Blaxel / Modal 账号或本机 Docker；
无端口、无数据库。

6. 方式一：pip 安装（推荐）

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?")

分享到 Hub：

agent.push_to_hub("m-ric/my_agent")
# 加载：agent.from_hub("m-ric/my_agent")

切换其他模型后端：

# LiteLLM（100+ 模型）
from smolagents import LiteLLMModel
model = LiteLLMModel(model_id="anthropic/claude-4-sonnet-latest",
                     temperature=0.2,
                     api_key=os.environ["ANTHROPIC_API_KEY"])

# OpenAI 兼容（Together / OpenRouter）
from smolagents import OpenAIModel
model = OpenAIModel(model_id="deepseek-ai/DeepSeek-R1",
                    api_base="https://api.together.xyz/v1/",
                    api_key=os.environ["TOGETHER_API_KEY"])

# 本地 transformers
from smolagents import TransformersModel
model = TransformersModel(model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
                          max_new_tokens=4096,
                          device_map="auto")

7. 方式二：CLI 与源码运行

# 通用多步 agent
smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7." \
  --model-type "InferenceClientModel" \
  --model-id "Qwen/Qwen3-Next-80B-A3B-Thinking" \
  --imports pandas numpy \
  --tools web_search

# 交互式向导
smolagent

# 浏览器 agent
webagent "go to xyz.com/men, get to sale section ..." --model-type "LiteLLMModel" --model-id "gpt-5"

源码开发：

git clone https://github.com/huggingface/smolagents.git
cd smolagents
pip install -e ".[dev]"

8. 配置项说明

配置	说明
`InferenceClientModel(model_id=..., provider=...)`	走 HF Inference Providers
`LiteLLMModel(model_id=..., api_key=...)`	走 LiteLLM 兼容 100+ 厂商
`OpenAIModel(model_id=..., api_base=..., api_key=...)`	任意 OpenAI 兼容端点
`TransformersModel(...)`	本地 transformers 模型
`AzureOpenAIModel(...)` / `AmazonBedrockModel(...)`	云厂商
`CodeAgent(tools=..., model=...)`	代码动作 agent
`Tool.from_mcp(...)` / `Tool.from_langchain(...)` / `Tool.from_space(...)`	接入外部工具

9. 常用运维命令

# 安装
pip install "smolagents[toolkit]"

# 升级
pip install -U "smolagents[toolkit]"

# 跑通用 agent
smolagent "<你的任务>"

# 交互式
smolagent

# 跑浏览器 agent
webagent "<任务描述>"

10. 常见故障排查

LocalPythonExecutor 安全告警：官方明确它不是沙箱，生产环境请换 E2B / Docker；
模型 401 / 403：检查对应 API Key 环境变量是否导出；
代码执行报错：用 stream_outputs=True 看模型生成的 Python 代码；
Hub push 失败：确认已 huggingface-cli login；
多模态输入：参考 vision_web_browser 示例。

11. 风险与合规说明

Apache-2.0 许可；
CodeAgent 会执行模型生成的 Python 代码，切勿在本地直接跑不可信任务；
模型调用费用由对应 Provider 账号承担；
本文为社区部署笔记，命令以官方文档最新版本为准。