用代码思考的智能体！

smolagents 是一个库，让您只需几行代码就能运行强大的智能体。它提供：

✨ 简单性：智能体的逻辑仅约1,000行代码（参见agents.py）。我们尽可能将抽象层简化到原始代码之上！

🧑‍💻 对代码智能体的一流支持。我们的CodeAgent以代码形式编写其行动（而非“智能体用于编写代码”）。为确保安全，我们支持通过Blaxel、E2B、Modal、Docker或Pyodide+Deno WebAssembly沙箱环境执行。

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

🌐 与模型无关：smolagents支持任何大语言模型。它可以是本地的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 加载智能体

我们的库与大语言模型无关：您可以将上述示例切换为任何推理服务提供商。

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

</details>
<details>
<summary> <b>本地 transformers 模型</b></summary>

```py
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 vs ToolCallingAgent）
• 从可用工具箱中选择工具
• 模型配置（类型、ID、API 设置）
• 高级选项，如额外导入
• 任务提示输入

与此同时，webagent 是一种专门的网页浏览智能体，使用 helium（更多信息请参阅这里)。

例如：

webagent "前往 xyz.com/men，进入促销专区，点击您看到的第一个服装商品。获取产品详情和价格，并返回。请注意，我是在法国购物" --model-type "LiteLLMModel" --model-id "gpt-5"

Code 智能体如何工作？

我们的 CodeAgent 的工作方式与经典的 ReAct 智能体基本相同——唯一的例外是，大语言模型引擎会将其动作写成 Python 代码片段。

flowchart TB
    Task[用户任务]
    Memory[智能体记忆]
    Generate[由智能体模型生成]
    Execute[执行代码动作——工具调用被写成函数]
    Answer[返回传递给 'final_answer' 的参数]

    Task -->|添加任务到智能体记忆| 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 = ["墨西哥湾美国", "格陵兰丹麦", "关税"]
for request in requests_to_search:
    print(f"以下是 {request} 的搜索结果：", web_search(request))

将动作写成代码片段已被证明比当前业界让大语言模型输出它想要调用的工具字典的做法更有效：减少了 30% 的步骤（从而减少了 30% 的大语言模型调用次数）并且在困难基准测试中达到了更高的性能。更多相关信息，请参阅我们关于智能体的高级介绍。

由于代码执行可能带来严重的安全问题（任意代码执行！），您应在沙箱中运行智能体代码。我们支持多种选项：

• E2B、Blaxel、Modal — 托管云沙箱，设置最简单
• Docker — 自托管容器隔离
• Pyodide+Deno WebAssembly — 轻量级沙箱，适用于浏览器或边缘环境

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

除了 CodeAgent，我们还提供了标准的 ToolCallingAgent，它将动作写成 JSON/文本块。您可以根据自己的用例选择最适合的风格。

这个库有多小巧？

我们力求将抽象程度控制在最低限度：agents.py 中的主代码行数不到1000行。

尽管如此，我们仍实现了多种类型的智能体：CodeAgent 会将其行动以 Python 代码片段的形式写出，而更经典的 ToolCallingAgent 则利用内置的工具调用方法。此外，我们还支持多智能体层级结构、从工具集合中导入功能、远程代码执行以及视觉模型……

顺便一提，为什么还要使用框架呢？嗯，因为这些功能中有很大一部分并不简单。例如，代码智能体必须在整个系统提示、解析器和执行过程中保持代码格式的一致性。因此，我们的框架帮你处理了这些复杂问题。当然，我们依然鼓励你深入研究源代码，只使用你需要的部分，而忽略其他一切！

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

我们用一些前沿模型创建了 CodeAgent 实例，并在 这个基准测试 上进行了对比。该基准测试汇集了来自多个不同基准的各类问题，旨在提供多样化的挑战。

基准测试代码请见这里，了解更多关于所用智能体设置的细节；同时，我们还对比了使用大语言模型代码智能体与普通模型的表现——（剧透：代码智能体的效果更好！）

这一对比表明，如今开源模型已经能够媲美甚至超越最好的闭源模型！

安全性

在使用执行代码的智能体时，安全性是一个至关重要的考量因素。请务必选用那些提供沙箱隔离功能的执行选项，以确保与不受信任的代码隔离开来。

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

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

欢迎贡献

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

引用 smolagents

如果你在论文中使用了 smolagents，请通过以下 BibTeX 条目进行引用。

@Misc{smolagents,
  title =        {`smolagents`: 一个轻量级库，用于构建出色的智能体系统。},
  author =       {阿耶梅里克·鲁歇尔、阿尔贝特·比利亚诺瓦·德尔莫拉尔、托马斯·沃尔夫、莱安德罗·冯·韦拉、埃里克·考尼斯马基},
  howpublished = {\url{https://github.com/huggingface/smolagents}},
  year =         {2025}
}

smolagents 快速上手指南

环境准备

• 系统要求：Python 3.8+
• 前置依赖：无强制依赖，推荐安装 pip 和 git
• 网络建议：为加速下载，可配置 pip 使用国内镜像源（如清华源）：

  pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
  

安装步骤

安装包含默认工具集的版本：

pip install "smolagents[toolkit]"

如需使用特定模型后端（如 OpenAI、Anthropic、本地模型），请根据需求额外安装对应依赖（如 litellm、transformers 等）。

基本使用

最简示例：创建一个能进行网页搜索的代码代理并运行任务：

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

✅ 默认使用 Hugging Face 推理服务，无需额外 API 密钥。
🔁 支持一键分享到 Hugging Face Hub：

agent.push_to_hub("your-username/your-agent")

支持切换模型后端（示例：使用 LiteLLM 调用 Anthropic）：

from smolagents import LiteLLMModel
import os

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

CLI 快速启动（交互式配置）：

smolagent

CLI 直接运行任务：

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" --tools web_search