smolagents：Hugging Face轻量级智能体库安装与使用指南
| 项目名称 | huggingface/smolagents |
| 仓库地址 | https://github.com/huggingface/smolagents |
| 官方网站 | https://huggingface.co/docs/smolagents |
| 官方文档 | smolagents Docs |
| 最新更新时间 | 2026-10-20（持续活跃更新） |
| 项目定位 | Hugging Face 官方轻量级 Agent 库，主打"用代码代替 JSON action"的 CodeAgent |
| 开源协议 | Apache-2.0 |
一、项目背景
大多数 Agent 框架让 LLM 输出一个 JSON：{"tool": "search", "args": {"q": "..."} }。但 JSON 对 LLM 来说其实很难——格式错一个引号就崩，复杂参数更别想。Hugging Face 的研究者提出一个大胆的想法：既然 LLM 最擅长写代码，那就让它直接写 Python 代码来调用工具。运行时把这段代码在沙箱里跑一遍，得到结果再喂回给 LLM。
这就是 smolagents 的核心思想。它由 Hugging Face 官方维护，核心代码只有几百行，却把"代码即动作"这个范式做到了极致：Agent 不是在选工具，而是在写一个 Python 脚本，脚本里可以自由组合工具、做循环、写条件、调用第三方库。这比传统 JSON 工具调用强大一个数量级。
smolagents 与 Hugging Face 生态深度集成：一行代码就能用 HfApiModel 调任何 Hugging Face 上的模型（包括免费 Inference API），内置 WebSearchTool、DuckDuckGoSearchTool、PythonREPLTool，还支持把任何 Hugging Face Space 变成工具。它已经成为 HF 官方教程里的 Agent 默认框架。
二、核心特性
- CodeAgent（代码即动作）：LLM 直接写 Python 代码调用工具，比 JSON action 灵活得多。
- ToolCallingAgent（传统模式）：也支持经典 JSON 工具调用，兼容老模型。
- 极轻量：核心库零依赖臃肿，import 即用。
- HfApiModel：一行接入 Hugging Face Inference API，免费额度可玩。
- 内置工具集：DuckDuckGo 搜索、Python REPL、网页抓取、文件 IO。
- 把 Space 变工具：
Tool.from_space("owner/space")一键复用 HF 上任何 Space。 - MCP 支持：可接入 Model Context Protocol 工具服务器。
- 多 Agent：可让一个 Manager Agent 派生子 Agent，分工协作。
三、环境要求
- Python：3.9+，推荐 3.10/3.11。
- 操作系统：Linux / macOS / WSL2。
- Hugging Face Token：用 HfApiModel 时需要（免费注册）。
- （可选）OpenAI Key：用 OpenAI 模型时需要。
- 磁盘：极小，几 MB。
四、详细部署步骤
第一步：安装
python3 -m venv .venv
source .venv/bin/activate
# 基础安装
pip install smolagents
# 带上默认工具集（web search 等）
pip install 'smolagents[toolkit]'
# 如果要用 litellm 接任意模型
pip install 'smolagents[litellm]'
# 如果要用 E2B 云沙箱跑不可信代码
pip install 'smolagents[e2b]'第二步：配置模型
import os
from smolagents import HfApiModel, InferenceClientModel
# 方式 A：用 Hugging Face Inference API（免费额度）
os.environ["HF_TOKEN"] = "hf_xxxx"
model = HfApiModel(model_id="meta-llama/Llama-3.3-70B-Instruct")
# 方式 B：用 OpenAI
from smolagents import OpenAIServerModel
model = OpenAIServerModel(
model_id="gpt-4o-mini",
api_key=os.environ["OPENAI_API_KEY"],
)
# 方式 C：用本地 Ollama
model = InferenceClientModel(model_id="http://localhost:11434/v1/qwen2.5:7b")第三步：第一个 CodeAgent
from smolagents import CodeAgent, DuckDuckGoSearchTool
agent = CodeAgent(
tools=[DuckDuckGoSearchTool()], # 给它一个搜索工具
model=model,
add_base_tools=True, # 自动加上 Python REPL 等基础工具
)
# 跑一个需要搜索 + 计算的任务
result = agent.run(
"巴黎到东京的空中距离是多少公里？"
"如果一只猎豹全速跑这段距离，需要多少秒？"
)
print(result)你会看到 Agent 自己写出类似这样的 Python 代码：
distance = web_search("distance Paris to Tokyo km")
speed = 100 / 3.6 # 猎豹约 100 km/h
time = distance / speed
final_answer(f"{time} 秒")第四步：自定义工具
from smolagents import tool
@tool
def get_weather(city: str) -> str:
"""查询城市天气。
Args:
city: 城市名，例如 Beijing
"""
# 这里接你的真实 API
return f"{city}: 晴，22℃"
agent = CodeAgent(tools=[get_weather], model=model)
agent.run("北京现在天气怎么样？")第五步：把 Hugging Face Space 变成工具
from smolagents import Tool
# 一键把任何 Space 包成工具
image_classifier = Tool.from_space(
space_id="microsoft/resnet-50",
name="image_classifier",
description="对图片做图像分类",
)
agent = CodeAgent(tools=[image_classifier], model=model)
agent.run("帮我分类这张图片: https://example.com/cat.jpg")第六步：多 Agent 协作
researcher = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model, name="researcher")
writer = CodeAgent(tools=[], model=model, name="writer")
manager = CodeAgent(
tools=[],
model=model,
managed_agents=[researcher, writer], # 派生子 Agent
name="manager",
)
manager.run("研究一下量子计算最新进展，然后写一段 200 字科普")第七步：MCP 工具接入
from smolagents import MCPServerStdio
server = MCPServerStdio(
params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]},
)
agent = CodeAgent(tools=[], model=model, mcp_servers=[server])五、进阶用法与生产建议
5.1 沙箱选型
CodeAgent 默认在本地 PythonREPL 执行 LLM 生成的代码，开发阶段没问题。生产环境请切到：
- E2B：
pip install smolagents[e2b]，云沙箱按秒计费； - Docker 沙箱：自己包一层 docker exec；
- 受限 PythonREPL：关闭
allow_dangerous_imports，禁掉 os/subprocess。
5.2 调试技巧
当 Agent 表现异常时：
agent = CodeAgent(..., verbosity_level=2)
# 打开后会打印每一步生成的 Python 代码与 stdout
# 方便定位是 Prompt 没说清，还是工具返回格式不对5.3 把 Agent 包成 API
from fastapi import FastAPI
app = FastAPI()
@app.post("/run")
def run(task: str):
result = agent.run(task, max_steps=8)
return {"result": result}六、使用方法示例
查看 Agent 思考过程：
agent = CodeAgent(..., verbosity_level=2) # 0/1/2 三档
agent.run("...")限制最大步数（防失控）：
agent.run("...", max_steps=10)保存与复用 Agent：
agent.save("my_agent")
# 之后加载
from smolagents import CodeAgent
loaded = CodeAgent.load("my_agent", model=model)典型任务示例：
- "查一下今天比特币价格，换算成人民币。"
- "把这个 CSV 文件读进来，画一张柱状图保存到 output.png。"
- "搜索 LangGraph 最新 release notes，总结三个新特性。"
默认账号密码：smolagents 是纯 Python 库，没有 Web 服务、不需要登录。使用 HfApiModel 时用 HF Token，使用 OpenAI 时用 OpenAI Key。
七、常见问题（FAQ）
Q1：CodeAgent 安全吗？它跑我机器上的 Python 代码？
默认在本地 PythonREPL 里执行 LLM 生成的代码，不要在生产直接用。生产请切到 E2B 云沙箱（sandbox-e2b）或 Docker 沙箱。
Q2：和 LangChain Agents 比有什么区别？
smolagents 核心只有几百行代码，理念极简；LangChain 生态大但抽象层多。smolagents 适合研究和轻量场景，LangChain 适合企业复杂工作流。
Q3：免费额度够用吗？
Hugging Face Inference API 对注册用户有免费额度，跑几个示例任务足够；生产请用付费模型或自建端点。
Q4：支持 DeepSeek 吗？
通过 OpenAIServerModel，把 base_url 改成 https://api.deepseek.com/v1 即可。
Q5：为什么叫 "smol"？
"smol" 是网络俚语"小小的、可爱的"，作者故意起这个名字表达"极简主义"——这个库真的只有几百行。
Q6：CodeAgent 和 ToolCallingAgent 怎么选？
新模型（GPT-4o、Claude 3.5、Qwen2.5）写代码能力强，优先 CodeAgent，灵活度高；老模型或只支持 function calling 的，用 ToolCallingAgent 更稳。
Q7：能和 LangChain 工具混用吗？
可以。from smolagents import LangChainTool 把任何 LangChain Tool 包一层即可。
八、跳转链接
- GitHub 仓库：https://github.com/huggingface/smolagents
- 官方文档：https://huggingface.co/docs/smolagents
- 博客介绍：Introducing smolagents
- PyPI：https://pypi.org/project/smolagents/
- Hugging Face 课程：Agents Course