smolagents

什么是 Smolagents？

Smolagents 是一个轻量级的开源 Python 库，旨在简化创建 AI 代理的过程，这些代理主要通过代码进行推理和执行操作。由 Hugging Face 团队开发，它以其极简主义方法脱颖而出，仅用大约 1,000 行核心代码就打包了强大的代理能力。与臃肿的框架不同，smolagents 剥离了不必要的抽象，专注于原始效率，同时支持高级功能，如安全的代码执行和与大型语言模型 (LLMs) 的无缝集成。

在其核心，smolagents 使开发者能够构建“用代码思考”的代理，这意味着 AI 生成 Python 代码片段来执行任务，而不是依赖僵硬的 JSON 工具调用。这种代码中心范式已被证明可以减少复杂工作流中的步骤高达 30%，使其非常适合需要多步骤推理的任务，例如网络搜索、数据分析或规划行程。无论您是使用开源模型进行实验的研究人员，还是部署生产代理的工程师，smolagents 都为代理式 AI 系统提供了灵活的基础。

Smolagents 如何工作？

Smolagents 基于 ReAct 启发的循环（推理和行动），但有一个转折：LLM 生成 Python 代码片段作为行动，而不是结构化输出。以下是其核心机制的分解：

• 代理初始化：您从定义一个代理开始，例如旗舰 CodeAgent，并为其配备工具（例如网络搜索、文件 I/O）和模型后端。

• 推理阶段：LLM（任何支持的模型）接收任务提示、过去的观察和可用工具。它逐步推理并输出描述预期行动的 Python 代码块。

• 执行阶段：代码片段在受控环境中执行。为了安全，smolagents 支持沙箱，如 E2B、Modal、Docker，甚至基于浏览器的 Pyodide 与 Deno WebAssembly。这可以防止任意代码损害您的系统。

• 观察和迭代：执行结果反馈到循环中，允许代理完善其方法，直到任务完成。

例如，要回答像“一只豹子以全速跑过 Pont des Arts 需要多少秒？”这样的查询，代理可能会生成代码来搜索豹子速度、桥梁长度并进行计算——所有这些都在一个高效的片段中。这与传统代理形成对比，后者可能需要多个工具调用，导致更多 LLM 调用和更高成本。

Smolagents 还包括 ToolCallingAgent 用于经典的 JSON 基于行动，给用户带来灵活性。支持多代理层次结构，其中一个代理委托给其他代理，从而提升复杂应用的 scalability。

Smolagents 的核心功能

尽管体积小，Smolagents 却功能强大。主要功能包括：

• 简单性和极简主义：agents.py 中的核心逻辑不到 1,000 行，便于理解、修改和扩展。没有陡峭的学习曲线——只是纯 Python。

• 模型无关设计：通过 Hugging Face 的 InferenceClient、LiteLLM（100+ 提供商）、OpenAI、Anthropic、本地 Transformers、Ollama、Azure 或 Amazon Bedrock 等集成，与任何 LLM 兼容。轻松切换模型而无需重写代码。

• 模态支持：处理文本、视觉、视频和音频输入。例如，视觉启用代理可以处理图像与文本提示一起，如专用教程所示。

• 工具灵活性：从任何地方集成工具——LangChain 库、MCP 服务器，甚至 Hugging Face Spaces。默认工具包包括 Web 搜索和代码执行等必需品。

• Hub 集成：直接从 Hugging Face Hub 分享和加载代理。将您的自定义代理作为 Space 仓库推送到协作：agent.push_to_hub("username/my_agent")。

• 安全执行：优先考虑安全，提供沙箱选项。E2B 和 Modal 提供基于云的隔离，而 Docker 适合本地设置。内置的安全 Python 解释器为较低风险环境添加额外层。

• CLI 工具：通过 smolagent 在命令行运行代理，用于一般任务（例如，使用 Web 搜索和数据导入的行程规划）或使用 Helium 的 webagent 用于浏览器自动化。

这些功能使 smolagents 适用于原型制作和生产，强调性能而非复杂性。

如何使用 Smolagents：一步步指南

入门很简单。通过 pip 安装：pip install "smolagents[toolkit]" 以包含默认工具。

基本代码代理示例

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel(model_id="microsoft/DialoGPT-medium")  # Or any LLM
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)
result = agent.run("Plan a trip to Tokyo, Kyoto, and Osaka between Mar 28 and Apr 7.")
print(result)

此设置利用代码生成进行多工具行动，如批量搜索或计算。

CLI 使用

对于无需脚本的快速运行：

• smolagent "Query here" --model-type InferenceClientModel --model-id Qwen/Qwen2.5-Coder-32B-Instruct --tools web_search --imports pandas numpy
• Web 特定：webagent "Navigate to site and extract details" --model-type LiteLLMModel --model-id gpt-4o

高级：沙箱执行

要启用 E2B 沙箱：

agent = CodeAgent(..., executor="e2b")  # Or "modal", "docker"

这确保代码在隔离环境中运行，对于不受信任的 LLM 输出至关重要。

分享和加载代理

导出到 Hub 以重复使用：

agent.push_to_hub("my_agent_space")
loaded_agent = CodeAgent.from_hub("my_agent_space")

理想用于团队项目或公共基准测试。

基准测试显示，像 Qwen2.5-Coder 这样的开源模型在代理任务中可以与闭源模型（如 GPT-4）匹敌，代码代理通过处理数学、搜索和规划等多样化挑战而优于 vanilla LLMs。

主要用例和实际价值

Smolagents 在需要高效代码驱动自动化的场景中大放异彩：

• 研究与开发：使用开源 LLM 原型代理工作流。研究人员可以对自定义任务基准模型，利用库的透明度。

• 数据分析和规划：代理处理 Web 抓取、计算和行程构建——例如，使用实时搜索和 pandas 数据处理的旅行规划。

• Web 自动化：使用 webagent 进行电子商务、内容提取或测试，安全模拟用户交互。

• 多模态任务：结合视觉模型进行图像分析与代码执行，例如处理视频帧或从视觉生成报告。

• 生产部署：通过 Hub Spaces 或 CLI 集成到应用中，实现可扩展、低延迟代理。

其实际价值在于效率：更少的 LLM 调用意味着更低的成本和更快的响应。例如，代码片段启用并行行动（例如，一次多个搜索），提升吞吐量 30%。它是 Apache-2.0 许可的，鼓励社区贡献——超过 185 名贡献者添加了如多语言文档和远程执行器等功能。

安全内置，处理代码执行风险通过沙箱和最佳实践，使其适合企业使用。

Smolagents 适合谁？

• 开发者和 AI 工程师：厌倦过度工程化框架的人会欣赏其可黑客的核心。为特定工具或层次自定义代理。

• 研究人员：在代理基准中测试开源 vs. 闭源模型；使用提供的 BibTeX 在论文中引用。

• 初创公司和团队：快速设置原型，Hub 分享用于协作。

• 业余爱好者：CLI 工具降低实验 AI 代理的门槛。

如果您正在构建代理系统并重视简单性而非臃肿，smolagents 是您的首选。为什么选择它？它使高级代理民主化，证明开源模型可以匹配专有能力，同时保持轻量和安全。

更多信息，请查看 huggingface.co/docs/smolagents 的完整文档，或深入 GitHub 仓库。通过指南贡献来塑造其未来！