smolagents：Hugging Face 出品的极简代码智能体库

官方信息表

项目背景与定位

smolagents 是 Hugging Face 推出的一个智能体（Agent）库，目标是让你只用几行代码就能跑起功能强大的智能体。项目名称里的"smol"意为"小巧"，作者刻意把抽象层削减到极致：智能体的核心逻辑压缩在大约 1000 行代码里（见仓库中的 agents.py），保持在"裸代码之上最精简的一层"，方便开发者直接读懂、按需取用。它的口号是"Agents that think in code!"——让智能体学会写代码、用代码思考，而不只是调用预设工具。正是这种设计取向，让它在开源智能体社区里迅速获得了广泛关注。

官方在 README 开头还放了 Hugging Face 吉祥物化身 James Bond 的插画，并配了一句口号"Agents that think in code!"——这正是 smolagents 区别于其他智能体框架的核心主张：让智能体直接写 Python 代码来完成任务，而不是把动作限制在预定义的 JSON 结构里。官方同时提醒读者，可以去看他们的发布博客了解这个项目诞生的更多背景。

按照官方 README，它的核心特性有六条：

• 极简（Simplicity）：智能体逻辑只有约 1000 行，抽象保持最精简的形态。
• 一等公民支持代码智能体（Code Agents）：官方主推的 CodeAgent 是让智能体自己写出代码来执行动作，而不是"用智能体去帮人写代码"。为了安全执行，官方支持在沙箱环境中运行，可选 Blaxel、E2B、Modal 或 Docker。
• Hub 集成：可以把工具或智能体分享到 Hugging Face Hub，也可以从 Hub 直接拉取——agent.push_to_hub("命名空间/仓库名") 一条命令就把你跑通的智能体变成一个 Space 仓库，别人用 agent.from_hub(...) 就能立即复用，实现高效智能体的即时共享。
• 模型无关（Model-agnostic）：支持任意 LLM——本地的 transformers 或 ollama 模型、Hub 上众多推理服务商，或通过 LiteLLM 集成接入 OpenAI、Anthropic 等几乎所有厂商。
• 模态无关（Modality-agnostic）：智能体支持文本、视觉、视频，甚至音频输入，视觉能力可参考网页浏览器教程。
• 工具无关（Tool-agnostic）：可以使用任意 MCP 服务器的工具、LangChain 的工具，甚至把一个 Hub Space 直接当作工具来用。

环境要求与安装

smolagents 是纯 Python 库，安装前只需准备好 Python 环境。官方推荐的一键安装命令如下（附带默认工具集）：

pip install "smolagents[toolkit]"

如果你打算本地生成文档做二次开发，官方文档给出了另外一套安装方式：在仓库根目录先 pip install -e . 安装项目本身，再用 pip install git+https://github.com/huggingface/doc-builder@main 安装文档构建器 hf-doc-builder，之后用 doc-builder build smolagents docs/source/en/ --build_dir ~/tmp/test-build 生成文档，或用 doc-builder preview smolagents docs/source/en/ 在 http://localhost:5173 预览。--build_dir 可以换成任意临时目录，命令会自动生成 MDX 文件。注意 preview 命令只对已有文件生效，新增文件时需要同步更新 _toctree.yml 并重启 preview。普通用户只需要前面那一条 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?")

这个示例问的是：一只全速奔跑的猎豹穿过巴黎艺术桥需要多少秒——智能体会自动联网搜索猎豹速度、桥长等信息并计算出结果。代码里 WebSearchTool() 就是给智能体装配的唯一工具，stream_outputs=True 则表示把智能体的思考与执行过程流式打印出来，方便你实时观察它每一步在干什么。README 正文还配了一段演示视频，直观展示智能体从接到问题、生成代码、调用搜索工具、到最终算出答案的完整过程，第一次接触代码智能体的用户强烈建议先看一遍建立直觉。

跑完之后，你还可以把智能体像 Space 仓库一样直接分享到 Hub：

agent.push_to_hub("m-ric/my_agent")

# 也可以从 Hub 加载别人分享的智能体
# agent.from_hub("m-ric/my_agent")

官方特别强调：这个库是 LLM 无关的，上面这个示例换成任意推理服务商的模型都能跑，不需要改动智能体定义本身。

接入任意模型后端

官方 README 用一组折叠块（details）的形式强调这个库是 LLM 无关的——上面的示例可以无缝换成任何推理服务商。这意味着你既可以用最便宜的本地模型，也可以随时切到最强的云端模型做对比，智能体代码一行都不用改。README 给出了七种模型接入方式，全部按原文翻译：

方式一：InferenceClientModel——Hugging Face Hub 上所有推理服务商的统一网关：

from smolagents import InferenceClientModel

model = InferenceClientModel(
    model_id="deepseek-ai/DeepSeek-R1",
    provider="together",
)

方式二：LiteLLModel——接入 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/", # 留空则查询 OpenAI 官方服务器
    api_key=os.environ["TOGETHER_API_KEY"], # 换成目标服务器对应的 API Key
)

方式四：OpenAI 兼容服务器——以 OpenRouter 为例：

import os
from smolagents import OpenAIModel

model = OpenAIModel(
    model_id="openai/gpt-4o",
    api_base="https://openrouter.ai/api/v1", # 留空则查询 OpenAI 官方服务器
    api_key=os.environ["OPENROUTER_API_KEY"],
)

方式五：本地 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")
)

命令行用法

smolagents 提供两个命令行工具：smolagent 和 webagent。

smolagent 是通用命令，可以跑一个多步的 CodeAgent，并为它装配各种工具：

# 直接带提示词和参数运行
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

交互模式会引导你完成全部配置：选择智能体类型（CodeAgent 还是 ToolCallingAgent）、从可用工具箱里挑选工具、配置模型（类型、ID、API 参数）、设置额外 import 等高级选项，最后输入任务提示词。也就是说，不写一行 Python 代码，只靠命令行向导也能跑起一个完整的智能体。

webagent 则是一个专门的网页浏览智能体，基于 helium 实现（helium 是对 Selenium 的高层封装，让网页操作像自然语言一样简单；更多实现细节见 vision_web_browser.py）。它的典型用法是把一套购物流程交给它：打开指定页面、进入折扣区、点进第一件衣服、拿到商品详情和价格——就像上面这条命令一样：

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"

工作原理：Code Agent 是怎么运转的

官方的 CodeAgent 大体上和经典的 ReAct 智能体一样——唯一的区别是：LLM 引擎输出的"动作"是 Python 代码片段，而不是一串 JSON。整个循环是这样的：用户任务被加入 agent.memory；然后进入 ReAct 循环——把记忆当作聊天消息喂给模型，模型输出后解析出代码动作，执行这段代码；如果没有调用 final_answer 工具，就把执行日志存回记忆并继续循环；一旦调用了 final_answer，就把该工具收到的参数作为最终答案返回。官方在 README 里用一张流程图把这个循环画了出来：任务进入记忆、记忆生成模型输出、模型输出解析成代码动作并执行、执行结果回灌记忆，直到 final_answer 被触发才跳出循环。

因为动作就是 Python 代码，工具调用也就自然变成了 Python 函数调用。官方给的例子是：智能体可以在一个动作里同时对多个网站发起搜索：

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

为什么要让智能体写代码而不是输出工具调用字典？官方引用了两篇论文说明：用代码片段表达动作比业界通行的字典式工具调用少用约 30% 的步骤（也就是少 30% 的 LLM 调用，见这篇论文），并且在困难基准上表现更好（见另一篇论文）。背后的直觉是：代码是一门足够丰富的"动作语言"——智能体可以在一个动作里写循环、写条件判断、打印中间结果，而不必被限制在预定义的工具 schema 里；这也让它天然具备多步推理和批量操作的能力。更多背景可以看官方的智能体概念入门。

安全执行沙箱

代码执行意味着任意代码执行，这是严肃的安全问题。官方明确要求：务必在沙箱里运行智能体代码。可选方案有三类：E2B、Blaxel、Modal——托管云沙箱，配置最简单；以及 Docker——自托管容器隔离。特别警告：内置的 LocalPythonExecutor 不是安全沙箱，它只做了部分限制、且可被绕过，绝不能当作安全边界来运行不可信代码。官方把"安全"单列为一个章节：在与会执行代码的智能体打交道时，安全是首要考量，必须使用能提供与不可信代码隔离的沙箱执行选项；安全政策、漏洞报告方式与安全执行的更多说明，见仓库根目录的 SECURITY.md。

除了 CodeAgent，官方还提供经典的 ToolCallingAgent，它按 JSON/文本块的形式输出动作。两种风格随你选，哪个更适合场景就用哪个。

开源模型在智能体工作流上的实力如何

官方用一些主流模型分别实例化 CodeAgent，在这个基准上做了对比——该基准汇集了多个来源的问题，形成风格各异的挑战组合。评测代码在 examples/smolagents_benchmark/run.py，其中还对比了"让 LLM 写代码"与"不写代码"的差别（剧透：代码智能体效果更好）。官方的对比结论是：开源模型如今已经能与最强的闭源模型正面竞争——开源模型 DeepSeek-R1 在智能体工作流上的表现超过了闭源模型。官方放的对比图标题也直接写明了这一点："在智能体工作流上，开源模型 DeepSeek-R1 击败了闭源模型"。

至于"这个库到底有多小"：官方强调主文件 agents.py 不到 1000 行，但仍然实现了多种类型的智能体（写代码的 CodeAgent、走内置工具调用的 ToolCallingAgent）、多智能体层级（multi-agent hierarchies）、工具集合导入、远程代码执行、视觉模型等能力。官方也解释了为什么还需要一个框架：因为系统提示词、解析器、执行器之间的代码格式必须全程保持一致，这些琐碎但重要的复杂性框架都帮你兜住了；当然，官方仍然鼓励你扒开源码，只拿走自己需要的部分，其余的一概不用。

FAQ 与参与贡献

问：smolagents 支持哪些模型？ 答：模型无关，任意 LLM 都行：本地 transformers/ollama、Hub 推理服务商、LiteLLM 接入的 OpenAI/Anthropic 等 100+ 家、Azure、Bedrock，以及任意 OpenAI 兼容服务器。

问：直接用 LocalPythonExecutor 跑网上抓来的智能体脚本安全吗？ 答：不安全。LocalPythonExecutor 不是安全边界，官方要求所有处理不可信代码的场景都必须使用 E2B、Blaxel、Modal 或 Docker 沙箱。

问：只想写工具调用而不想写代码怎么办？ 答：用官方同时提供的 ToolCallingAgent，按 JSON/文本块输出动作即可。

问：如何参与贡献？ 答：阅读官方贡献指南，提交 PR 即可。文档规范遵循 Google docstring 风格，新增教程时在 docs/source/en/ 下加 Markdown 文件，并在 _toctree.yml 里登记目录。如果重命名了章节标题或把一节移到别的文档里，官方建议在文件末尾留一段"已迁移章节"锚点映射，保证旧链接（很可能已被 issue、论坛、社交网络引用）依然能跳转到正确位置。

问：可以把别的生态的工具接进来吗？ 答：可以。smolagents 是工具无关的：任意 MCP 服务器的工具、LangChain 工具都能直接包装成 smolagents 的 Tool，甚至一个 Hugging Face Hub Space 都能被当作工具来调用。

问：智能体之间可以互相协作吗？ 答：可以，官方在约 1000 行的主代码里仍实现了多智能体层级（multi-agent hierarchies），让你可以搭建分工协作的智能体团队。

问：视觉、音频这类非文本输入支持吗？ 答：支持。smolagents 是模态无关的——智能体可以处理文本、视觉、视频乃至音频输入，视觉浏览能力可以参考官方的网页浏览器教程。

如果在学术发表中使用了 smolagents，官方建议引用：

@Misc{smolagents,
  title =        {`smolagents`: a smol library to build great agentic systems.},
  author =       {Aymeric Roucher and Albert Villanova del Moral and Thomas Wolf and Leandro von Werra and Erik Kaunismäki},
  howpublished = {\url{https://github.com/huggingface/smolagents}},
  year =         {2025}
}

跳转链接

• 项目仓库：huggingface/smolagents
• 官方文档：smolagents Docs
• 发布博客：Introducing smolagents
• 基准数据：agents_medium_benchmark_2
• 安全策略：SECURITY.md
• 在线问答：DeepWiki