SmolAgents — 以极简代码构建可执行工具调用 Agent

用代码思考的智能体！

smolagents 是一个库，让你能用几行代码运行强大的智能体。它提供：

✨ 简洁性：智能体的核心逻辑仅约 1,000 行代码（参见 agents.py）。我们在底层代码之上保持了最精简的抽象！

🧑‍💻 对代码智能体的一流支持。我们的 CodeAgent 用代码编写其动作（而不是"用智能体来写代码"）。为确保安全，我们支持通过 Blaxel、E2B、Modal、Docker 或 Pyodide+Deno WebAssembly 沙箱在沙盒环境中执行代码。

🤗 Hub 集成：你可以将工具或智能体分享到 Hub 或从 Hub 拉取，即时分享最高效的智能体！

🌐 模型无关：smolagents 支持任何 LLM。可以是本地的 transformers 或 ollama 模型、Hub 上的众多推理提供商之一，或通过我们的 LiteLLM 集成支持 OpenAI、Anthropic 等任何模型。

👁️ 模态无关：智能体支持文本、图像、视频甚至音频输入！参见此教程了解视觉功能。

🛠️ 工具无关：你可以使用来自任何 MCP 服务器 的工具、来自 LangChain 的工具，甚至可以将 Hub Space 用作工具。

完整文档请访问此处。

[!NOTE]
查看我们的发布博客文章以了解更多关于 smolagents 的信息！

快速演示

首先安装包含默认工具集的包：

pip install "smolagents[toolkit]"

然后定义你的智能体，赋予它所需的工具并运行！

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("一只猎豹以全速跑过艺术桥需要多少秒？")

https://github.com/user-attachments/assets/84b149b4-246c-40c9-a48d-ba013b08e600

你甚至可以将智能体分享到 Hub，作为一个 Space 仓库：

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

# agent.from_hub("m-ric/my_agent") 从 Hub 加载智能体

我们的库是 LLM 无关的：你可以将上面的示例切换到任何推理提供商。

from smolagents import InferenceClientModel

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

from smolagents import LiteLLMModel

model = LiteLLMModel(
    model_id="anthropic/claude-4-sonnet-latest",
    temperature=0.2,
    api_key=os.environ["ANTHROPIC_API_KEY"]
)

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 密钥。
)

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"], # 切换为你目标服务器的 API 密钥。
)

from smolagents import TransformersModel

model = TransformersModel(
    model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
    max_new_tokens=4096,
    device_map="auto"
)

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

import os
from smolagents import AmazonBedrockModel

model = AmazonBedrockModel(
    model_id = os.environ.get("AMAZON_BEDROCK_MODEL_ID") 
)

CLI

你可以使用两个命令从 CLI 运行智能体：smolagent 和 webagent。

smolagent 是一个通用命令，用于运行可以配备各种工具的多步骤 CodeAgent。

# 使用直接提示和选项运行
smolagent "计划一次 3 月 28 日至 4 月 7 日期间前往东京、京都和大阪的旅行。"  --model-type "InferenceClientModel" --model-id "Qwen/Qwen3-Next-80B-A3B-Thinking" --imports pandas numpy --tools web_search

# 以交互模式运行（未提供提示时启动设置向导）
smolagent

交互模式将引导你完成：
- 智能体类型选择（CodeAgent 与 ToolCallingAgent）
- 从可用工具箱中选择工具
- 模型配置（类型、ID、API 设置）
- 高级选项，如额外导入
- 任务提示输入

同时，webagent 是一个特定的网页浏览智能体，使用 helium（了解更多此处）。

例如：

webagent "访问 xyz.com/men，进入促销区，点击你看到的第一个服装商品。获取产品详情和价格，并返回它们。注意我从法国购物" --model-type "LiteLLMModel" --model-id "gpt-5"

代码智能体如何工作？

我们的 CodeAgent 工作方式大多类似于经典的 ReAct 智能体——不同之处在于 LLM 引擎将其动作编写为 Python 代码片段。

flowchart TB
    Task[用户任务]
    Memory[agent.memory]
    Generate[从 agent.model 生成]
    Execute[执行代码动作 - 工具调用被编写为函数]
    Answer[返回给 'final_answer' 的参数]

    Task -->|将任务添加到 agent.memory| Memory

    subgraph ReAct[ReAct 循环]
        Memory -->|将记忆作为聊天消息| Generate
        Generate -->|解析输出以提取代码动作| Execute
        Execute -->|未调用 'final_answer' 工具 => 将执行日志存储在内存中并继续运行| Memory
    end

    Execute -->|调用 'final_answer' 工具| Answer

    %% 样式
    classDef default fill:#d4b702,stroke:#8b7701,color:#ffffff
    classDef io fill:#4a5568,stroke:#2d3748,color:#ffffff

    class Task,Answer io

动作现在是 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))

将动作编写为代码片段已被证明比当前行业实践（让 LLM 输出一个它想要调用的工具字典）效果更好：减少 30% 的步骤（从而减少 30% 的 LLM 调用），并且在困难基准测试中达到更高性能。前往我们对智能体的高级介绍了解更多。

由于代码执行可能带来严重的安全隐患（任意代码执行！），你应该在沙箱中运行智能体代码。我们支持多种选项：
- E2B、Blaxel、Modal —— 托管的云沙箱，设置最简单
- Docker —— 自托管的容器隔离
- Pyodide+Deno WebAssembly —— 适用于浏览器或边缘环境的轻量级沙箱

内置的 LocalPythonExecutor 不是安全沙箱。它应用了一些限制，但可能被绕过，不得用作安全边界。

除了 CodeAgent，我们还提供了标准的 ToolCallingAgent，它将动作编写为 JSON/文本块。你可以选择最适合你用例的风格。

这个库有多"小巧"？

我们努力将抽象保持在最低限度：agents.py 中的主要代码不到 1,000 行。
尽管如此，我们实现了多种类型的智能体：CodeAgent 将其动作编写为 Python 代码片段，而更经典的 ToolCallingAgent 则利用内置的工具调用方法。我们还有多智能体层次结构、从工具集合导入、远程代码执行、视觉模型……

顺便问一下，为什么要使用框架呢？嗯，因为这些东西大部分都不简单。例如，代码智能体必须在其系统提示、解析器和执行过程中保持一致的代码格式。所以我们的框架为你处理了这种复杂性。当然，我们仍然鼓励你深入研究源代码，只使用你需要的部分，排除其他一切！

开源模型在智能体工作流中的表现如何？

我们使用一些领先的模型创建了 CodeAgent 实例，并在这个基准测试上进行了比较，该基准汇集了来自几个不同基准测试的问题，提出了多样化的挑战。

在此处查找基准测试代码以获取有关所用智能体设置的更多详细信息，并查看使用 LLM 代码智能体与原始模型（剧透：代码智能体效果更好）的比较。

这个比较表明，开源模型现在可以挑战最好的闭源模型！

安全

在使用执行代码的智能体时，安全是一个关键考虑因素。确保你使用的是提供隔离不受信任代码的沙箱化执行选项之一。

警告： LocalPythonExecutor 仅提供尽力而为的缓解措施，不是安全边界。不要用它来运行不受信任的代码。

有关安全策略、漏洞报告以及安全智能体执行的更多信息，请参阅我们的安全策略。

贡献

欢迎所有人贡献，请从我们的贡献指南开始。

引用 smolagents

如果你在出版物中使用了 smolagents，请使用以下 BibTeX 条目进行引用。

@Misc{smolagents,
  title =        {`smolagents`: 一个构建强大智能体系统的小巧库。},
  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}
}