smolagents—— 一款支持“用代码思考”的智能体！ - 文章 - 开发者社区

什么是smolagents？

smolagents是一个轻量级智能体库，只需几行代码即可运行强大的智能体。它具有以下亮点功能：

✨ 简洁易用 ：智能体的核心逻辑代码仅约 1000 行 （详见 agents.py[1]），抽象层级极少，几乎接近原始代码级别的控制感！

🧑‍💻 原生支持 Code Agent（代码智能体） ：smolagents 的 CodeAgent 智能体通过“写代码”来执行动作（不同于“用智能体写代码”）。为确保运行安全，支持在 沙箱环境 中执行，如：E2B 安全沙箱[2] ，Docker 容器执行。

🤗Hub 集成 ：支持将工具或智能体上传到 Hub或从 Hub 获取[3]，方便即刻分享或复用高效智能体组件。

🌐 模型无关 ：smolagents 支持任意 LLM 模型：本地 Transformers 模型， Ollama 模型，Hub 上的多个模型提供方[4] ，OpenAI、Anthropic 等，均通过 LiteLLM 接口[5]兼容支持。

👁️ 多模态支持 ：支持文本、视觉、视频，甚至音频输入！参见视觉输入示例：Vision Tutorial[6]

🛠️ 工具无关 ：支持来自以下任意来源的工具调用：MCP 服务器[7] ， LangChain ，Hub Space[8]（甚至可以把一个 Space 作为一个工具用）。

📘 文档与说明

•📄 查看完整文档[9]•📢 阅读我们的发布博客[10]

⚡ 快速演示：用代码跑一个 Agent！

1️⃣ 安装

  
pip install smolagents[toolkit]  
  
from smolagents importCodeAgent,WebSearchTool,InferenceClientModel  
  
# 初始化模型  
model =InferenceClientModel()

2️⃣ 创建智能体并运行任务

  
# 创建 CodeAgent，赋予它网页搜索工具  
agent =CodeAgent(  
    tools=[WebSearchTool()],  
    model=model,  
    stream_outputs=True  
)  
  
# 运行智能体，执行自然语言指令  
agent.run("一只猎豹全速跑过巴黎艺术桥需要多少秒？")

🎬 演示视频：smolagents_readme_leopard.mp4[11]

你可以将自己构建的智能体分享到 Hub，作为一个 Space 仓库（repository）进行托管和复用：

  
# 推送智能体到 Hub  
agent.push_to_hub("m-ric/my_agent")  
  
# 从 Hub 加载智能体  
# agent = agent.from_hub("m-ric/my_agent")

全面兼容主流 LLM 模型（LLM-Agnostic）：smolagents 支持多种推理引擎与模型平台，只需轻松切换即可运行在不同的环境中。

CLI

你可以使用以下两条命令行工具运行智能体： smolagent和 webagent。

smolagent 是一个通用型命令，用于运行多步骤的 CodeAgent，可以灵活加载多个工具。

  
smolagent "规划一次 3 月 28 日至 4 月 7 日之间的东京、京都和大阪之旅。" \  
--model-type "InferenceClientModel" \  
--model-id "Qwen/Qwen2.5-Coder-32B-Instruct" \  
--imports "pandas numpy" \  
--tools "web_search"

webagent 是一个专门用于网页浏览的智能体，基于 helium[13] 实现网页自动操作。

  
webagent "访问 xyz.com/men，进入促销区，点击看到的第一件服装，获取商品详情和价格。注意我正在法国购物。" \  
--model-type "LiteLLMModel" \  
--model-id "gpt-4o"

CodeAgent 是如何工作的？

CodeAgent[14] 的行为类似于经典的 ReAct 智能体（即“推理 + 行动”），但与之不同的是： LLM 会直接用 Python 代码片段来表达要执行的操作！

picture.image

在 CodeAgent 中，智能体的行动（Action）现在是以 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% 的操作步骤[15]，减少约 30% 的 LLM 请求次数，在复杂基准测试中表现更优[16]。想了解更多？请查看我们的智能体设计高级指南[17]。

由于这种方式需要执行 LLM 自动生成的 Python 代码，因此我们提供了多种机制来提升运行安全性：

•一个安全的 Python 解释器，可以在你的环境中更安全地运行代码（比直接执行原始代码更安全，但仍存在风险）•使用 E2B[18] 或 Docker 的沙箱环境（消除了对你本地系统的风险）

除了 CodeAgent[19]，我们还提供标准的 ToolCallingAgent[20]，其将行动写为 JSON 或文本块。你可以根据自己的使用场景选择最适合的风格。

这个库到底有多“轻”？

我们力求将抽象保持在最低限度：核心逻辑代码集中在 agents.py 文件中，不足 1000 行代码 。即便如此，我们依然实现了多种类型的智能体： CodeAgent将行动写成 Python 代码片段， ToolCallingAgent使用更经典的内建工具调用方式，同时支持多智能体层级结构，工具集合导入，远程代码执行，视觉模型等扩展功能。

为什么还需要使用框架？因为很多底层细节并不简单 。以 CodeAgent 为例，它必须在整个系统提示、代码解析器和执行阶段保持代码格式的一致性 。我们构建这个框架，就是为了帮你处理这些繁杂的部分。但我们依然鼓励你深入源代码 ，只使用你真正需要的部分 ，抛弃一切冗余。

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

我们使用多个主流开源模型创建了CodeAgent 实例，并在一个综合基准测试[21]中进行了比较。该基准测试汇集了多个经典问答任务，旨在评估智能体在多种挑战下的表现能力。

对比结果表明：CodeAgent 智能体在执行效果上优于传统调用方式（Vanilla LLM） 。想了解更多？你可以查看基准测试用的代码和设置说明[22]。

picture.image

这项对比表明：开源模型现在已经具备挑战最佳闭源模型的能力！

安全性

在使用具有代码执行能力的智能体 时，安全性是关键考量因素。我们提供以下保障措施：

•使用 E2B 或 Docker 进行沙箱隔离执行•提供执行智能体代码的最佳安全实践

🔎 查看我们的安全政策[23] 获取更多关于漏洞报告、隔离策略等信息。

参与贡献

我们欢迎所有人参与贡献！请参阅我们的贡献指南[24] 来开始第一步。

论文引用

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

  
@Misc{smolagents,  
  title ={`smolagents`: a smol library to build great agentic systems.},  
  author ={AymericRoucherandAlbertVillanovadelMoralandThomasWolfandLeandro von WerraandErikKaunismäki},  
  howpublished ={\url{https://github.com/huggingface/smolagents}},  
  year ={2025}  
}

更多信息

山行AI希望本文对你有所帮助。更多信息请看：https://github.com/huggingface/smolagents?tab=readme-ov-file，感谢点赞、转发！

References