Smolagents

Smolagents 快速入门

HuggingFace 出品 —— 让 Agent 用代码思考，而不是用文字。

这是什么？适合谁？

Smolagents 是 HuggingFace 推出的轻量级 Agent 框架。它最大的不同点是「Agent 的思考媒介是 Python 代码，不是自然语言」——Agent 直接生成并执行 Python 代码片段来完成任务，而不是像 ReAct 那样用文字描述下一步。GitHub 28.5K+ stars（截至 2026-07），Apache-2.0 开源。

核心代码只有约 1000 行（agents.py），抽象层很薄，「上面就是 raw code」。提供两种 Agent 类：

• CodeAgent：用 Python 代码作为动作（默认推荐）。
• ToolCallingAgent：用传统 JSON/tool-call 方式调用工具，跟其他框架对齐。

适合谁？一是 HuggingFace 生态用户（Hub 集成顺畅）；二是想用「代码作为动作」的开发者（HuggingFace 论文显示这种范式比传统 JSON 工具调用少 30% 步骤）；三是做研究/对比实验的人（核心代码 1000 行，可读性极强）。不适合：完全不想跑代码执行环境的用户；也不适合国内网络环境（默认走 HuggingFace Hub Inference，需要访问外网）。

准备工作

1. Python 3.10 及以上：访问 python.org 下载安装。
2. pip 或 uv：Python 3.10+ 自带 pip；推荐 uv（安装更快、依赖解析更稳）。
3. 模型 API Key：可选 HuggingFace Token（免费）、OpenAI、Anthropic，或本地 Ollama 模型。
4. 代码沙箱（生产环境推荐）：默认 LocalPythonExecutor 不是安全沙箱，必须用 E2B / Blaxel / Modal / Docker 之一做隔离。

环境变量：HF_TOKEN（HuggingFace Hub）或 OPENAI_API_KEY 等。

3 步快速上手

第 1 步：安装

pip install "smolagents[toolkit]"

[toolkit] extra 会拉一组常用内置工具（WebSearchTool、DuckDuckGo 等）。如果只用自己定义的 tool，可以裸装：pip install smolagents。

第 2 步：创建 Agent

新建 hello_agent.py，粘贴下面代码：

from smolagents import CodeAgent, InferenceClientModel

model = InferenceClientModel()  # 默认用 HuggingFace Hub Inference
agent = CodeAgent(tools=[], model=model)
agent.run("计算 1 到 100 的所有整数之和")

跑通后会看到 Agent 生成并执行一段 Python 代码（通常是 sum(range(1, 101))），然后输出 5050。

注意：InferenceClientModel 是 1.x 之后的推荐 API，老教程里的 HfApiModel 仍然能用，但官方推荐迁移到 InferenceClientModel（统一了 HuggingFace Inference Providers 网关）。

第 3 步：添加工具

from smolagents import CodeAgent, InferenceClientModel, WebSearchTool

model = InferenceClientModel()
agent = CodeAgent(
    tools=[WebSearchTool()],
    model=model,
    stream_outputs=True,   # 流式打印思考过程
)
agent.run("北京今天的天气怎么样？")

WebSearchTool 是官方内置工具，Agent 会把它当作 Python 函数来调用（例如 web_search("北京天气")）。stream_outputs=True 会把每一步的执行日志实时打印出来，调试时强烈建议开启。

想接其他模型也很简单——把 InferenceClientModel 换成 LiteLLMModel、OpenAIModel、AzureOpenAIModel、TransformersModel（本地）即可。

常见踩坑

踩坑 1：HfApiModel 找不到/报错

• 症状：从老代码或教程复制示例，from smolagents import HfApiModel 报 ImportError 或运行时提示方法签名不匹配
• 原因：Smolagents 1.x 之后 API 重构，HfApiModel 已被 InferenceClientModel 取代，统一了 HuggingFace Inference Providers 网关接口
• 解决：将代码中的 HfApiModel 全局替换为 InferenceClientModel；如果仍要用老 API，固定版本 pip install smolagents==0.5.x
• 参考：GitHub Issue #501

踩坑 2：LocalPythonExecutor 运行时安全问题

• 症状：Agent 生成的 Python 代码直接在本机执行，产生意外副作用（修改文件、删除数据）
• 原因：默认 LocalPythonExecutor 仅提供「best-effort mitigations」，官方文档明确声明其不是安全边界（not a security boundary）
• 解决：生产环境必须使用 E2B、Blaxel、Modal 或 Docker 沙箱；在 CodeAgent(..., executor=e2b_executor) 中传入隔离执行器；个人本地 demo 可暂用默认 executor，但绝不能暴露给不可信用户
• 参考：GitHub Issue #429（Groq API 模型兼容性讨论中也涉及沙箱安全问题）

踩坑 3：Agent 死循环不出 final_answer

• 症状：Agent 反复生成代码、执行、再生成，进入无限循环，永远不输出最终答案
• 原因：CodeAgent 必须显式调用 final_answer(...) 才结束循环；默认 max_steps=6 对复杂任务不足，模型卡在中间步骤无法收敛
• 解决：CodeAgent(..., max_steps=15) 增加步数上限；在 system prompt 中明确指示「得出最终答案后调用 final_answer()」；设置 max_execution_time 兜底防卡死
• 参考：GitHub Issue #640（多 Agent 代码执行失败相关死循环问题）

踩坑 4：WebSearchTool 报 401/403 认证失败

• 症状：运行 agent.run("搜索...") 时 WebSearchTool 报 HTTP 401 或 403，搜索功能不可用
• 原因：HuggingFace Hub 的搜索走 Inference Providers 服务，需要带 HF_TOKEN 的认证请求；默认未设置 token
• 解决：在 huggingface.co/settings/tokens 创建一个有 inference 权限的 token；export HF_TOKEN=hf_xxx 写入环境变量或 .env 文件；如果用 InferenceClientModel，可在构造时传入 token=...
• 参考：GitHub Issue #133（安装依赖相关问题，token 问题在讨论区广泛出现）

踩坑 5：pip install smolagents[all] 依赖冲突

• 症状：pip install smolagents[all] 安装了大量不必要依赖（torch、transformers 等），且与已有项目冲突
• 原因：[all] extra 包含 [transformers]、[litellm]、[mcp]、[toolkit] 等多个子包的聚合，其中 torch 等重型库安装耗时且容易版本冲突
• 解决：先装最小集 pip install smolagents，再按需加入 [toolkit]（内置工具）、[litellm]（LiteLLM 模型）、[transformers]（本地模型）等，依赖更可控
• 参考：GitHub Issue #251（类似初始化问题引发的依赖讨论）

踩坑 6：Agent 输出的代码 import pandas 失败

• 症状：Agent 在沙箱中执行 import pandas / import numpy 时报 ModuleNotFoundError
• 原因：CodeAgent 默认 additional_authorized_imports 为空列表，不允许导入未显式声明的第三方库
• 解决：CodeAgent(..., additional_authorized_imports=["pandas", "numpy"]) 显式加入白名单；或修改 prompt 要求 Agent 只用 Python 标准库
• 参考：GitHub Issue #1179（MCP 工具导入上下文管理相关讨论，同样涉及 import 权限）

踩坑 7：换模型后 Agent 代码质量骤降

• 症状：从 GPT-4o 切换到 DeepSeek-V2/Llama-3 等模型后，Agent 生成大量语法错误的 Python 代码
• 原因：CodeAgent 依赖模型本身的代码生成能力；小模型（< 7B）在代码任务上普遍弱于大模型，且 CodeAgent 范式对模型要求比 ToolCallingAgent 更高
• 解决：用 GPT-4o / Claude Sonnet / DeepSeek-V3 等强模型起步调试；弱模型建议改用 ToolCallingAgent（生成 JSON 工具调用而非代码）；在 prompt 中加示例代码格式约束
• 参考：GitHub Issue #60（MCP 集成讨论中也反映了模型能力差异的影响）

踩坑 8：Windows 中文 prompt 报 UnicodeDecodeError

• 症状：在 Windows 终端运行 Agent 时，输入中文后报 UnicodeDecodeError: 'gbk' codec can't decode byte
• 原因：Windows 中文版默认控制台编码为 GBK，而 Python 默认使用系统编码读取 stdin/stdout，中文字符被误解码
• 解决：运行前执行 set PYTHONIOENCODING=utf-8 或 chcp 65001 切换控制台编码到 UTF-8；或在 VS Code / IDE 内置终端中运行（默认 UTF-8）
• 参考：GitHub Issue #24（Conversational agent 初始问题及编码相关讨论）

初级用法

• 内置工具：WebSearchTool、DuckDuckGoSearchTool、PythonInterpreterTool、VisitWebpageTool——一行导入就能用。
• 自定义 tool：用 @tool 装饰器写 Python 函数，docstring 会被传给模型当工具描述。
• MCP 工具：from smolagents import ToolCollection; tools = ToolCollection.from_mcp(...)，一行接入任意 MCP Server。
• Hub 分享：agent.push_to_hub("your-username/my-agent")，把整个 Agent（包含 tools / model / system prompt）发布成 Hub Space，下次 agent.from_hub(...) 一键加载。
• CLI 模式：smolagent "Plan a trip to Tokyo..." 不写 Python 也能跑（适合快速验证 prompt）。

高级玩法

• 沙箱执行（生产必备）：接 E2B 沙箱，CodeAgent(tools=[...], model=model, executor=e2b_executor)。Agent 的代码会在云端隔离环境里跑，主机不会受污染。
• 多 Agent 层级：managed_agent 字段把一个 Agent 塞给另一个 Agent 当 tool，构建「主编 Agent + 调研 Agent」这种二级结构。
• vision/audio 输入：CodeAgent 支持图片、视频、音频作为输入（依赖模型本身的多模态能力，例如 Qwen/Qwen2-VL）。
• 代码 Agent benchmark：仓库 examples/smolagents_benchmark/ 提供 GAIA、HotpotQA 等基准测试脚本，可以拿自己的模型去跑分。
• 本地 transformers 模型：TransformersModel(model_id="Qwen/Qwen3-...", device_map="auto")，纯本地推理，无需 API Key。
• LiteLLM 路由 100+ 模型：LiteLLMModel(model_id="anthropic/claude-4-sonnet-latest", api_key=...)，通过 LiteLLM 间接支持任意 OpenAI 兼容服务。

小技巧

1. 开启 stream_outputs=True：调试时实时看 Agent 写的代码和执行结果，比跑完再排查省一半时间。
2. max_steps 别用默认值：默认 6 步对复杂任务容易不够；生产环境建议 15-20，再加 max_execution_time 兜底防卡死。
3. docstring 是 Agent 的「说明书」：自定义 tool 时 docstring 写清楚「什么时候用、输入是什么、返回什么」，调用率会显著提升。
4. Hub Token 提前准备好：第一次跑 WebSearchTool 就要 token，建议直接 export HF_TOKEN=hf_xxx 写到 ~/.bashrc / $PROFILE 里。
5. 不要混用 CodeAgent 和 ToolCallingAgent：两者的 prompt 模板不一样，混用容易 prompt 互相干扰。同一项目选一个范式。
6. 跟 LangChain 工具互通：Tool.from_langchain(langchain_tool) 可以直接复用 LangChain 生态的 tool，无需重写。

进阶学习建议

如果你想从「能跑通 Smolagents」走到「能在产品里用 Smolagents」，按这条路径走最快：

1. 先看 README + 官方博客：smolagents 启动博文 讲清了「为什么用代码做动作」的设计动机。
2. 跑 examples 目录：仓库 examples/ 里有 web_browser、multiagent、vision、多模态等十几个完整例子，比文档更直观。
3. 理解 ReAct 循环：读 agents.py 里的 CodeAgent.run() 流程——Task → Memory → Generate Code → Execute → 循环直到 final_answer。
4. 接沙箱：默认 executor 不安全，先把 E2B 沙箱跑通，再考虑 Modal / Docker。
5. 对比 benchmark：用 examples/smolagents_benchmark/ 测自己的 prompt + 模型组合，跟官方报告做对比。
6. Hub 发布 Agent：把自己调好的 Agent push 到 Hub，既是备份也能让团队复用。

可以对比阅读的几个相关项目：LangChain Agents、CrewAI、OpenAI Agents SDK。

FAQ

Q1: Smolagents 是免费的吗？

A1: 软件本身 Apache-2.0 开源免费。运行成本来自模型 API：默认走 HuggingFace Hub Inference（免费额度有限），自配 OpenAI/Anthropic 按调用计费（GPT-4o-mini 约 ¥0.001/次），或本地跑 transformers/Qwen 模型（0 边际成本，只需显卡）。

Q2: 和 LangChain Agents 有什么区别？

A2: LangChain 是「全家桶」，LCEL、Retrievers、Memory、Output Parsers 一应俱全；Smolagents 是「极简派」，只做 Agent 核心，代码 1000 行。如果你想快速搭一个完整 RAG / 复杂工作流，选 LangChain；如果你想要「最小抽象 + 可读源码 + 代码即动作」，选 Smolagents。两者也可以共存——Tool.from_langchain(...) 能把 LangChain 的 tool 接到 Smolagents 里。

Q3: 必须用代码沙箱吗？

A3: 看你场景。生产环境/对外服务：必须用沙箱（E2B/Blaxel/Modal/Docker）；个人学习、本地 demo、不接受外部输入的场景，用默认 LocalPythonExecutor 也行——但别把这种用法暴露给不可信用户。

Q4: 支持中文吗？

A4: 模型本身支持就行（Qwen、DeepSeek、GLM 都强）。Smolagents 不限制语言——Agent 的思考代码、用户 prompt、最终回答都可以是中文。

Q5: 跟 LangGraph / CrewAI 比呢？

A5: LangGraph 偏「图编排」（节点 + 边 + 状态机），适合复杂确定性流程；CrewAI 偏「角色扮演」（Agent = 员工 + 角色 + 背景故事），适合内容流水线；Smolagents 偏「单 Agent + 工具」，多 Agent 只是「managed_agent」的二级嵌套。三者经常组合用——LangGraph 控流程，CrewAI 做内容生产，Smolagents 做单步推理。

参考链接

• Smolagents GitHub
• Smolagents 官方文档
• Smolagents 启动博客
• Code-as-Action 论文 (HuggingFace)
• E2B 沙箱文档

免责声明

本文涉及的 GitHub stars 数、版本号、价格等信息基于公开资料整理（截至 2026-07），实际数据请以各项目仓库为准。Smolagents 仍在活跃迭代，API 接口可能在后续版本变化，部署到生产前请阅读最新 README 和 CHANGELOG。文中代码示例仅供学习参考，请在遵循各项目许可证的前提下使用。