GitHub - huggingface/smolagents: 🤗 smolagents：一个用代码思考的极简 Agent 库
smolagents 是 Hugging Face 推出的轻量级 Agent 库，核心逻辑约 1000 行代码，主打 CodeAgent——让大模型把动作写成 Python 代码片段执行，工具调用即函数调用；同时提供传统 ToolCallingAgent，支持任意 LLM、多模态输入、MCP/LangChain/Hub Space 工具、Hub 分享，并可通过 E2B、Blaxel、Modal、Docker 做沙箱执行。
社区作者 · zZz
它解决什么问题
项目定位
smolagents 是一个让你用几行代码就能跑起强大 Agent 的库，官方口号是「用代码思考的 Agent（Agents that think in code!）」。它把 Agent 逻辑压缩到约 1000 行代码（见 agents.py），尽量只在原始代码之上保留最薄的抽象。
核心特性
- ✨ 简洁：Agent 逻辑约 1000 行代码，抽象层极薄，鼓励直接改源码、只取所需部分。
步骤 2 · 🧑💻 一等公民级别支持 Code Agents：CodeAgent 把动作写成代码（而不是「用 Agent 去写代码」）。为安全起见，支持在沙箱环境执行，可选 Blaxel、E2B、Modal 或
Docker。
- 🤗 Hub 集成：可以把工具或 Agent 推送/拉取到 Hub，方便即时共享最高效的 Agent。
- 🌐 模型无关：支持任何 LLM——本地 transformers 或 ollama 模型、Hub 上的众多推理提供商，或通过 LiteLLM 集成接入 OpenAI、Anthropic 等大量模型。
- 👁️ 模态无关：Agent 支持文本、视觉、视频甚至音频输入（视觉可参考官方教程）。
- 🛠️ 工具无关：可以使用任何 MCP 服务器的工具、LangChain 工具，甚至把一个 Hub Space 当作工具。
配图 1 为项目形象图（Hugging Face 吉祥物扮成 James Bond），配图 2 为不同模型在 agentic 工作流上的基准对比，显示开源模型 DeepSeek-R1 可超越闭源模型。
Code Agent 怎么工作
CodeAgent 大体上像经典 ReAct Agent，区别在于 LLM 引擎把动作写成 Python 代码片段。流程为：用户任务 → 写入 agent.memory → 以聊天消息形式把记忆交给 agent.model 生成 → 解析输出提取代码动作 → 执行代码动作（工具调用写成函数）→ 若未调用 final_answer 工具则把执行日志存回记忆继续循环，调用 final_answer 则返回其参数作为答案。
正文给出的一次动作内多次搜索示例：
requests_to_search = ["gulf of mexico america", "greenland denmark", "tariffs"]
for request in requests_to_search:
print(f"Here are the search results for {request}:", web_search(request))官方称，把动作写成代码片段比当前业界常见的「让 LLM 输出工具调用字典」效果更好：步骤减少 30%（因此 LLM 调用减少 30%），在困难基准上性能更高。
安全提示
代码执行存在严重安全风险（任意代码执行），必须在沙箱中运行 Agent 代码。支持的选项：E2B、Blaxel、Modal（托管云沙箱，最简单）；
Docker（自托管容器隔离）。内置的 LocalPythonExecutor 不是安全沙箱，它只做了一些限制但可被绕过，不得作为安全边界使用，不要用它运行不可信代码。
库到底有多小
主代码 agents.py 少于 1000 行。同时仍实现了多种 Agent：CodeAgent（动作写成 Python 代码片段）、更经典的 ToolCallingAgent（用内置工具调用方法）、多 Agent 层级、从工具集合导入、远程代码执行、视觉模型等。官方解释框架的价值在于处理非平凡复杂度：代码 Agent 需要在系统提示、解析器、执行之间保持一致的代码格式，框架替你处理这些；但仍鼓励深入源码，只使用需要的部分。
开源模型在 Agent 工作流上的表现
官方用若干领先模型构造 CodeAgent 实例，在一个汇集多个基准问题的评测集上对比，结果显示开源模型已能与最好的闭源模型抗衡。
许可证与引用
来源正文未标注仓库许可证，需到仓库页面核验（待核验）。若在出版物中使用 smolagents，正文给出 BibTeX 引用：author 为 Aymeric Roucher、Albert Villanova del Moral、Thomas Wolf、Leandro von Werra、Erik Kaunismäki，year 为 2025，howpublished 为 https://github.com/huggingface/smolagents。
— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。
安装 / 开始使用
1. 准备环境
需要一个可用的 Python 环境（正文未给出具体 Python 版本要求，待核验）。若要用本地模型或调用云推理服务，需自行准备对应的 API Key 或本地推理环境。
2. 安装（含默认工具集）
pip install "smolagents[toolkit]"3. 定义并运行第一个 Agent
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?")正文在示例后附有演示视频 smolagents_readme_leopard.mp4。
4. 把 Agent 分享到 Hub（作为 Space 仓库）
agent.push_to_hub("m-ric/my_agent")
# agent.from_hub("m-ric/my_agent") to load an agent from Hub5. 切换不同模型后端（库是 LLM-agnostic 的）
- InferenceClientModel：HF 上所有推理提供商的统一入口
from smolagents import InferenceClientModel
model = InferenceClientModel(
model_id="deepseek-ai/DeepSeek-R1",
provider="together",
)- LiteLLM 接入 100+ LLM
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 AI）
import os
from smolagents import OpenAIModel
model = OpenAIModel(
model_id="deepseek-ai/DeepSeek-R1",
api_base="https://api.together.xyz/v1/", # Leave this blank to query OpenAI servers.
api_key=os.environ["TOGETHER_API_KEY"], # Switch to the API key for the server you're targeting.
)- OpenAI 兼容服务器（OpenRouter）
import os
from smolagents import OpenAIModel
model = OpenAIModel(
model_id="openai/gpt-4o",
api_base="https://openrouter.ai/api/v1", # Leave this blank to query OpenAI servers.
api_key=os.environ["OPENROUTER_API_KEY"], # Switch to the API key for the server you're targeting.
)- 本地 transformers 模型
from smolagents import TransformersModel
model = TransformersModel(
model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
max_new_tokens=4096,
device_map="auto"
)- Azure 模型
import os
from smolagents import AzureOpenAIModel
model = AzureOpenAIModel(
model_id=os.environ.get("AZURE_OPENAI_MODEL"),
azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
api_version=os.environ.get("OPENAI_API_VERSION")
)- Amazon Bedrock 模型
import os
from smolagents import AmazonBedrockModel
model = AmazonBedrockModel(
model_id=os.environ.get("AMAZON_BEDROCK_MODEL_ID")
)6. 命令行（CLI）
提供两个命令：smolagent 与 webagent。 smolagent 是通用命令，用于运行可装配多种工具的多步 CodeAgent：
# Run with direct prompt and options
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
# Run in interactive mode (launches setup wizard when no prompt provided)
smolagent交互模式（不提供 prompt 时启动配置向导）会依次引导你完成：
- Agent 类型选择（CodeAgent vs ToolCallingAgent）
- 从可用工具箱中选择工具
- 模型配置（类型、ID、API 设置）
- 高级选项，如额外 import
- 任务提示词输入
webagent 是基于 helium 的专用网页浏览 Agent，例如：
webagent "go to xyz.com/men, get to sale section, click the first clothing item you see. Get the product details, and the price, return them. note that I'm shopping from France" --model-type "LiteLLMModel" --model-id "gpt-5"7. 沙箱执行（首次运行代码 Agent 前务必确认）
- E2B、Blaxel、Modal：托管云沙箱，配置最简单。
- Docker：自托管容器隔离。
- 注意：内置 LocalPythonExecutor 不是安全沙箱，只提供尽力而为的限制，可被绕过，不得作为安全边界，不要用它运行不可信代码。
8. 常见问题
- 想换模型：直接替换 model 的构造类（InferenceClientModel / LiteLLMModel / OpenAIModel / TransformersModel / AzureOpenAIModel / AmazonBedrockModel）。
- 想要 JSON/文本动作而不是代码动作：改用 ToolCallingAgent。
- 想用现成工具：可从 MCP 服务器、LangChain、Hub Space 引入。
- 安全策略与漏洞上报：见项目 Security Policy；贡献流程见 contribution guide。
