上周我在调试一个棘手的数据管道问题——在解析 30 种不同地区格式的 CSV 文件时总有些对不上。我只能在编辑器、终端和 Stack Overflow 之间来回切，手动跑 Python 代码片段来验证猜想。切了两个小时上下文后，我心想：“我只想要一个能直接写代码、跑代码的 agent，而且我一分钱都不想给 OpenAI。”
正是这个痛点，让我找到了 smolagents——Hugging Face 推出的极简 agent 框架。这名字真没开玩笑——它确实很小，但特别能打，尤其是当你想在本地用开源模型跑通一切的时候。下面我就来聊聊我是怎么把它跑通的，踩了哪些坑，以及我对它的真实评价。
配置环境：出乎意料地无痛
大多数 agent 框架在你写第一行业务逻辑之前，非得让你在 YAML 配置里苦熬 40 分钟。smolagents 却让人耳目一新，完全不是这样。
首先，安装库：
pip install smolagents
这是核心安装。如果你想跑本地模型（这也是我用它的全部理由），你还得确保装了 transformers 和 torch：
pip install smolagents[transformers] torch
接下来是我踩的第一个坑：我本以为需要配置一个复杂的本地推理服务器。我花了 20 分钟试图搞定 vLLM，后来才意识到 smolagents 可以直接加载本地模型。如果你要下载受限模型（gated models），只需要一个 Hugging Face 令牌，把它设为环境变量就行：
export HF_TOKEN="your_token_here"
用开源模型跑你的第一个 Agent
smolagents 最核心的卖点是：它把代码作为主要的动作空间。Agent 不是去拼装 JSON 工具调用，而是直接写 Python 代码并执行。这对数据处理任务来说简直是巨大的优势。
下面是我用 Qwen2.5-Coder-7B 搭建本地 agent 的过程，这可是个写代码的超强开源模型：
from smolagents import CodeAgent, HfApiModel, TransformersModel
# 选项 1：通过 Transformers 使用本地模型
# 这会下载模型并在本地 GPU 上运行
model = TransformersModel(
model_id="Qwen/Qwen2.5-Coder-7B-Instruct",
device_map="auto"
)
# 选项 2：如果你的 GPU 显存不够，可以用 HF 的推理 API 跑开源模型
# （还是比用 OpenAI 便宜！）
# model = HfApiModel(model_id="Qwen/Qwen2.5-Coder-7B-Instruct")
agent = CodeAgent(
tools=[],
model=model,
add_base_tools=True # 添加计算器、Python 解释器等基础工具
)
result = agent.run(
"Read the file 'sales_data.csv', find the top 5 regions by revenue, "
"and plot them as a bar chart. Save the chart as 'top_regions.png'."
)
print(result)
跑这段代码时，agent 生成了真正的 Python 代码，用 pandas 和 matplotlib 读取数据、画图、保存文件，最后返回了总结。没有 JSON 工具的格式定义，也没有容易出错的解析。就是纯纯的代码。
“顿悟”时刻：自定义工具
内置工具确实不错，但真正的威力在于写你自己的工具。我需要一个能查询公司内部指标数据库的工具，写起来竟然这么简单：
from smolagents import Tool
class MetricsQueryTool(Tool):
name = "metrics_query"
description = (
"Queries the internal metrics database. "
"Pass a SQL query and get back results as a list of dictionaries."
)
inputs = {
"query": {
"type": "string",
"description": "The SQL query to execute"
}
}
output_type = "string"
def forward(self, query: str) -> str:
import sqlite3
# 在生产环境中，这里会连接到真实的数据库
conn = sqlite3.connect("metrics.db")
cursor = conn.execute(query)
columns = [desc[0] for desc in cursor.description]
results = [dict(zip(columns, row)) for row in cursor.fetchall()]
conn.close()
return str(results)
# 把工具接入 agent
agent = CodeAgent(
tools=[MetricsQueryTool()],
model=model,
add_base_tools=True
)
agent.run("What were our top 3 performing campaigns last month?")
Agent 会读取工具的描述，自己琢磨出需要构造一个 SQL 查询，调用工具，然后再处理结果——全程自主。因为 agent 是在 Python 环境里运作的，它甚至能在给你最终答案前，先用 pandas 对查询结果做二次处理。
踩坑记录
有几个地方让我猝不及防：
1. 模型的选择极其重要。 我一开始用 Llama-3.1-8B 试，agent 生成的 Python 代码总是有毛病——不是缺了 import，就是变量没定义。换成 Qwen2.5-Coder-7B 之后，简直是一个天上一个地下。如果你要用 smolagents 搞代码任务，一定要用专门写代码的模型。目前 Qwen2.5-Coder 和 DeepSeek-Coder 是最好的开源选择。
2. 本地 7B 模型搞不定复杂的多步推理。 当我给 agent 布置需要 4 到 5 个连续步骤的任务时，7B 模型经常跑到一半就脱轨了。升级到 Qwen2.5-Coder-32B（通过 Hugging Face API 调用）解决了这个问题，但那显然就不算纯本地运行了。这个取舍是真实存在的。
3. 执行沙箱跑的是真 Python。 Agent 直接对自己生成的代码执行 exec()。在本地做实验，这没啥问题；但在生产环境里，你得小心了。自从 agent 不小心删了我的测试数据库后，我就把 agent 调用包在 Docker 容器里了。听我一句劝，千万别大意。
4. 上下文太长时显存吃紧。 当我塞给 agent 一个 50 页的 PDF 让它分析时，我 16GB 显存的 GPU 瞬间就爆显存了。用本地模型时，你得小心翼翼地控制上下文长度，或者对于处理文档的任务，干脆把活儿甩给 HF Inference API。
实战案例：自动化代码审查
这是我现在真在用的东西。我搭了个 agent，在本地推代码前先让它帮我审查 pull request：
from smolagents import CodeAgent, TransformersModel
model = TransformersModel(
model_id="Qwen/Qwen2.5-Coder-7B-Instruct",
device_map="auto"
)
agent = CodeAgent(tools=[], model=model, add_base_tools=True)
review = agent.run(
"Read the file 'src/utils/helpers.py' and review it for: "
"1) Potential bugs or edge cases, "
"2) Performance issues, "
"3) Missing error handling. "
"Provide specific line numbers and suggestions."
)
print(review)
它虽然不如资深开发审查得那么细致，但抓些明显的问题足够了——比如没检查 None 值、缺了异常处理、或者 O(n²) 的循环。在我的 RTX 3090 上，大概 30 秒就能跑完。
大实话测评
我喜欢的点：
- API 真的极简。不到 10 行代码，你就能从零跑起一个能用的 agent。
- 对于涉及数据处理的任务，代码优先的 agent 比 JSON 工具调用的 agent 强太多了。
- 对开源模型的一等公民级支持。没有厂商锁定。
- 自定义工具写起来和接进去都简单得离谱。
局限之处：
- 小型本地模型（7B 参数）很快就会碰到推理天花板。只要是超过 2-3 步的任务，你就需要 32B 以上的模型，而这通常意味着得用 API。
- 没有内置沙箱。代码执行是动真格的，你要是不留神，agent 真的能搞出破坏。
- 错误恢复能力一般。当 agent 生成的代码报错时，它有时会陷入死循环，一直生成同样行不通的代码，而不是换个思路。
- 文档还比较少。我花了不少时间看源码，才搞明白工具的输入是怎么校验的。
总结： 当你想要 agent 的能力，又不想搞 LangChain 那套繁琐的配置，也不想付 GPT-4 那么高的成本时，smolagents 就是绝佳选择。它非常适合个人自动化、数据探索和本地开发工作流。只是别指望你笔记本上跑的 7B 模型能替代一整个工程师团队——甚至替代不了一个提示词写得好的 GPT-4 调用。把它用在它擅长的领域：那些快速的、代码驱动的任务，在这些场景下，保持本地运行和开源，比追求极致能力更重要。