Smolagents

<a href="https://github.com/huggingface/smolagents/blob/main/LICENSE"><img alt="许可证" src="https://img.shields.io/github/license/huggingface/smolagents.svg?color=blue"></a>
<a href="https://huggingface.co/docs/smolagents"><img alt="文档" src="https://img.shields.io/website/http/huggingface.co/docs/smolagents/index.html.svg?down_color=red&down_message=offline&up_message=online"></a>
<a href="https://github.com/huggingface/smolagents/releases"><img alt="GitHub 发布版本" src="https://img.shields.io/github/release/huggingface/smolagents.svg"></a>
<a href="https://github.com/huggingface/smolagents/blob/main/CODE_OF_CONDUCT.md"><img alt="贡献者公约" src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg"></a>
<a href="https://deepwiki.com/huggingface/smolagents"><img src="https://deepwiki.com/badge.svg" alt="向 DeepWiki 提问"></a>

用代码思考的 Agent！

smolagents 是一个库，只需几行代码即可运行强大的 Agent。它具备以下特点：

✨ 简单易用：Agent 的逻辑只需约 1,000 行代码（参见 agents.py）。我们将抽象精简到最简形式，让代码保持直观！

🧑‍💻 一流的编码 Agent 支持。我们的 CodeAgent 会用代码编写自己的操作（而不是“用 Agent 来编写代码”）。为确保安全，我们支持通过 Blaxel、E2B、Modal 或 Docker 在沙盒环境中执行代码。

🤗 Hub 集成：你可以在 Hub 上分享或拉取工具和 Agent，轻松分享效率最高的 Agent！

🌐 不受模型限制：smolagents 支持任何大模型。它可以是本地的 transformers 或 ollama 模型、Hub 上的众多服务提供商之一，也可以是来自 OpenAI、Anthropic 等厂商的模型，并通过我们的 LiteLLM 集成接入。

👁️ 不受模态限制：Agent 支持文本、图像、视频，甚至音频输入！有关视觉功能，请参阅本教程。

🛠️ 不受工具限制：你可以使用来自任何 MCP 服务或 LangChain 的工具，甚至可以将 Hub Space 用作工具。

完整文档请见此处。

说明

查看我们的发布博客文章，了解有关 smolagents 的更多信息！

快速演示

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

pip install "smolagents[toolkit]"

然后定义你的 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?")

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

你甚至可以将 Agent 作为 Space 仓库分享到 Hub：

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

# agent.from_hub("m-ric/my_agent") to load an agent from 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/", # 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.
)

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

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 运行 Agent：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

交互模式会引导你完成以下操作：

• 选择 Agent 类型（CodeAgent 或 ToolCallingAgent）
• 从可用工具箱中选择工具
• 配置模型（类型、ID、API 设置）
• 设置其他导入等高级选项
• 输入任务提示词

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

Code Agent 的工作原理

我们的 CodeAgent 的工作方式与经典的 ReAct Agent 大体相同，区别在于大模型引擎会将操作写成 Python 代码片段。

flowchart TB
    Task[User Task]
    Memory[agent.memory]
    Generate[Generate from agent.model]
    Execute[Execute Code action - Tool calls are written as functions]
    Answer[Return the argument given to 'final_answer']

    Task -->|Add task to agent.memory| Memory

    subgraph ReAct[ReAct loop]
        Memory -->|Memory as chat messages| Generate
        Generate -->|Parse output to extract code action| Execute
        Execute -->|No call to 'final_answer' tool => Store execution logs in memory and keep running| Memory
    end
    
    Execute -->|Call to 'final_answer' tool| Answer

    %% Styling
    classDef default fill:#d4b702,stroke:#8b7701,color:#ffffff
    classDef io fill:#4a5568,stroke:#2d3748,color:#ffffff
    
    class Task,Answer io

现在，操作是 Python 代码片段。因此，工具调用将作为 Python 函数调用执行。例如，Agent 可以通过单个操作在多个网站上执行网页搜索：

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%），并且在困难基准测试中表现更佳。请参阅我们的 Agent 高阶简介以了解更多信息。

由于代码执行可能带来严重的安全隐患（任意代码执行！），你应该在沙箱中运行 Agent 代码。我们支持多种方案：

• E2B、Blaxel、Modal — 托管式云沙箱，设置最简单
• Docker — 可自托管的容器隔离

内置的 LocalPythonExecutor 不是安全沙箱。它会实施一些限制，但这些限制可能被绕过，因此不得将其用作安全边界。

除了 CodeAgent，我们还提供标准的 ToolCallingAgent，它会将操作写成 JSON/文本块。你可以根据使用场景选择最合适的风格。

这个库有多精简？

我们努力将抽象严格控制在最低限度：agents.py 中的主要代码不到 1,000 行。 不过，我们实现了多种类型的 Agent：CodeAgent 会将其操作编写为 Python 代码片段，而更经典的 ToolCallingAgent 则利用内置的工具调用方法。我们还支持多 Agent 层级结构、从工具集合导入、远程代码执行、视觉模型……

顺便问一下，为什么要使用框架？因为这类功能中有很大一部分并不简单。例如，代码 Agent 必须确保代码在系统提示词、解析器和执行过程中格式一致。因此，我们的框架会为你处理这些复杂性。当然，我们仍鼓励你深入研究源代码，只使用你需要的部分，舍弃其他所有内容！

开源模型在 Agent 工作流中的表现如何？

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

点击此处查看基准测试代码，了解所用 Agent 设置的更多详情；还可以查看 LLM 代码 Agent 与普通 LLM 的对比（剧透：代码 Agent 表现更好）。

这项比较表明，开源模型如今已经能够挑战最优秀的闭源模型！

安全性

使用能够执行代码的 Agent 时，安全性至关重要。请确保使用能够隔离不可信代码的沙盒执行选项之一。

警告：LocalPythonExecutor 仅提供尽力而为的缓解措施，并非安全边界。请勿使用它运行不可信代码。

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

参与贡献

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

引用 smolagents

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

@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}
}