smolagents

smolagents 是一个用于构建自主 AI 代理的 Python 库，由 Hugging Face 于 2024 年 12 月 31 日发布。该库的核心理念是，代理应该通过编写和执行 Python 代码来采取行动，而不是像大多数其他框架那样生成 JSON 工具调用字典。核心代理逻辑仅约 1,000 行代码，这是经过深思熟虑的设计：整个框架具有极高的可读性和可审计性，开发者在一个下午就能完成二次开发。smolagents 采用 Apache 2.0 许可，截至 2026 年 5 月，其在 GitHub 上已获得 27,000 颗星，成为自 LangChain 以来采用速度最快的代理框架之一。

该库提供两种代理类型：CodeAgent（生成 Python 代码片段作为操作并在沙盒解释器中执行，与基于 JSON 的工具使用相比，可减少 30% 的 LLM 调用）和 ToolCallingAgent（遵循标准 JSON 工具调用格式，以兼容 OpenAI 风格的 API）。它通过 LiteLLM 支持 100 多种模型后端，包括通过 Ollama 和 Hugging Face Transformers 进行的本地推理，以及 OpenAI、Anthropic 和任何具有 OpenAI 兼容端点的提供商。代理和工具可以通过 Hugging Face Hub 进行共享和拉取。支持多模态输入（文本、视觉、视频、音频）。沙盒执行选项包括 E2B、Modal、Docker、Blaxel 和 WebAssembly 环境，专为在生产环境中运行不可信代码的团队设计。

2026 年 4 月的 smolagents 实际功能

smolagents 运行一个多步推理循环：代理接收任务，询问 LLM 下一步该做什么，执行生成的操作（作为 Python 代码或工具调用），观察输出，并重复此过程，直到任务完成或达到步数限制。CodeAgent 变体在每一步将其转换为可执行的 Python 代码，而不是 JSON 操作对象。一个最小的可运行代理只需三行 Python 代码：导入库，使用工具列表和模型实例化 CodeAgent，然后调用 agent.run("your task")。

1.24.0 版本（2026 年 1 月）扩展了多代理架构，其中管理者 CodeAgent 可以将子任务委托给专门的子代理。Hub 集成意味着发布到 Hugging Face Hub 的任何工具或代理配置都可以通过一行代码导入。2025 年初添加了 MCP 服务器兼容性，因此 smolagents 可以使用通过 Model Context Protocol 暴露的工具，以及原生 Python 工具和兼容 LangChain 的工具。

该库发布初期的 GAIA 基准测试结果确立了其可信度：使用 smolagents 架构构建的 CodeAgent 在 GAIA 验证集上得分为 44.2%（发布时排名第一），击败了微软 AutoGen 的 40%，并远高于在没有代理框架的情况下同一基准测试中 GPT-4-Turbo 不到 7% 的基准得分。GAIA 测试在识别艺术品、匹配历史文档和处理结构化数据等复杂任务中的高级规划、多模态推理和多步信息收集能力。到 2025 年底，进一步的优化将基于 smolagents 的系统在 GAIA 上的得分推高至 55%，巩固了代码优先方法在需要可组合、有状态计算的任务上的优势。

smolagents 与 LangChain 和 PydanticAI 的定位对比

smolagents 最常被拿来与 LangChain/LangGraph（占据主导地位的现有框架）、PydanticAI（类型安全优先的新秀）以及在较小程度上与 LlamaIndex 进行比较。它们各自代表了关于代理框架应该是什么的不同理念。

LangChain 和 LangGraph 拥有超过 90,000 颗 GitHub 星和五年的生产历史。LangGraph 使用有向无环图 (DAG) 架构扩展了 LangChain，其中代理步骤是显式的图节点，使开发者能够精确控制分支逻辑、状态机、重试和错误传播。这种控制伴随着繁琐的步骤：在运行单个操作之前，定义 LangGraph 工作流需要显式的节点定义、边缘和状态模式。smolagents 在其 1,000 行的核心代码中自动处理 ReAct 循环；您只需提供工具和模型，循环就会为您管理。对于具有人在回路 (human-in-the-loop) 检查点和细粒度错误处理的复杂有状态编排，LangGraph 是正确的选择。smolagents 的原型设计速度更快，但在规模化时可控性较差。

PydanticAI 于 2024 年 9 月发布，并于 2025 年 9 月达到 v1.0 版本，它将 FastAPI 风格的结构化验证引入了代理开发。每个工具调用和代理输出在处理之前都会根据 Pydantic 模式进行验证，并内置了 OpenTelemetry 检测和异步优先设计。PydanticAI 与 smolagents 的机制差异在于输出强制执行：smolagents 生成 LLM 编写的任何 Python 代码并信任该代码是有效的，而 PydanticAI 在每个边界强制执行模式契约。对于医疗记录、财务数据管道或任何需要可审计、可预测的结构化响应的应用程序，PydanticAI 的验证保证至关重要。smolagents 没有提供等效的机制。代价是 PydanticAI 的严格类型增加了设置开销，而这正是 smolagents 刻意避免的。

对于已经投入 Hugging Face 生态系统、通过 Ollama 使用 Transformers 或开源模型，或者构建研究原型的团队来说，smolagents 具有明显的主场优势。对于运行处理敏感结构化数据的生产应用程序的团队来说，LangGraph 的控制或 PydanticAI 的验证值得增加复杂性。用户通常将 smolagents 与 Hugging Face Hub 结合使用以获取模型和共享工具，或者通过 smolagents 的 LangChain 兼容层与 LangChain 工具结合使用。

“如果 JSON 片段是更好的表达方式，那么 JSON 就会成为顶级的编程语言，而编程将变成人间地狱。” - Aymeric Roucher、Merve Noyan 和 Thomas Wolf，Hugging Face 工程团队，smolagents 发布博客，2024 年 12 月

代理循环的实际情况

在 smolagents 中运行 CodeAgent 意味着 LLM 在每一步都在生成 Python 代码。当模型具有强大的代码生成能力时，这非常有效。当能力不足时，循环会迅速退化：代理编写语法错误的 Python 代码，解释器抛出异常，错误被附加到上下文中，然后要求 LLM 修复它。在功能强大的模型（GPT-4o、Claude Sonnet、DeepSeek-R1、Qwen2.5-Coder）上，这种自我纠正循环非常稳健。在通用的小型模型上，它会产生令人沮丧的失败代码螺旋，白白消耗 Token 而毫无进展。

内存管理是 GitHub issues 中最常被提及的痛点。代理维护每个操作和观察的完整历史记录。在长任务中，这段历史会增长并超出模型的上下文窗口。与 Claude Code 的摘要方法（滚动压缩较旧的上下文）不同，截至 2026 年初，smolagents 没有内置的内存整合功能。GitHub issue #694 直接描述了这个问题：“基本的截断和消息删除，但没有内置的摘要来管理长期内存增长。” 2025 年 3 月提交的 Issue #901 证实“与内存相关的工具尚未在 smolagents 中公开，这对于更高级的代理应用程序来说是一个限制。” Issue #1121（2025 年 4 月）是关于持久性长期内存库的功能请求。这些都是公开路线图上已知的空白。

沙盒代码执行有文档记录，但分层级。在本地运行 CodeAgent 使用受限的 Python 解释器（基于 AST，具有导入控制和操作计数上限）。为了实现更严格的隔离，可以使用 E2B、Modal、Docker 和 WebAssembly 沙盒，但多代理架构目前不支持沙盒执行器，这意味着管理者代理及其子代理在同一个执行上下文中运行。处理不可信输入的生产部署需要明确地围绕此限制进行架构设计。

“从 smolagents 目前的功能到运行生产级应用程序的代理框架所需的一切，还有很长的一段路要走。” - agentsdecoded.com 框架评论，2025 年

构建研究和数据科学工作流的用户报告了最流畅的体验。一个典型的模式：定义 5-10 个工具（DuckDuckGo 搜索、Python REPL、文件读取器、API 客户端），实例化一个 CodeAgent，并交给它一个开放式的研究任务。代理编写 Python 代码来链接工具调用，在变量中处理中间结果，并返回结构化输出，而无需开发者编写任何编排逻辑。用户经常将 smolagents 与 DSPy 结合使用以进行提示词优化，或与 PydanticAI 结合使用以在混合管道中进行输出验证。

smolagents 是为谁构建的

smolagents 适合已经习惯用 Python 思考并希望框架开销最小化的机器学习研究人员、数据科学家和后端开发者。Hugging Face 生态系统集成（Hub 模型、Hub 工具、Transformers、Datasets）使其成为已经在使用该技术栈的团队的自然首选。如果您的模型部署是在本地运行 Llama 或 Qwen 的 Ollama，或者是 Hugging Face Inference Endpoints 上的微调模型，smolagents 是显而易见的起点：集成是原生的，许可证是兼容的，并且代码库足够小，易于阅读和修补。

开源模型用户尤其受益，因为 smolagents 通过 LiteLLM 兼容性平等对待所有模型。对于受限模型或专有优化，没有高级付费层。针对 GPT-4o 运行的同一个 CodeAgent，只需更改一个配置即可针对本地 Qwen2.5-Coder 模型运行。探索代理架构而不希望被供应商锁定的团队会喜欢这种灵活性。对于探索多代理协调，托管代理模式（顶级代理编排子代理）开箱即用，无需额外配置。在检索增强生成 (RAG) 输入到使用代码处理检索上下文的代理的管道中，该库是对 LlamaIndex 的完美补充。

smolagents 不是什么

smolagents 不是生产级的企业代理平台。除了开发者手动添加的内容之外，它没有内置的可观测性、结构化日志记录或重试策略。没有模式强制的输出，没有原生的审计跟踪，也没有合规性认证。在受监管行业（医疗保健、金融、法律）中评估用于生产部署的代理框架的团队会发现，PydanticAI 的验证契约或 LangGraph 的显式状态管理更符合他们的治理要求。

它对弱模型也不宽容。代码优先的方法需要一个能够在提示词压力下编写干净、功能正常的 Python 代码的 LLM。尝试在较小的通用模型（参数大约低于 7B，或未专门针对代码进行训练的模型）上运行 smolagents 会产生不可靠的结果。对于希望在消费级 GPU 上自托管一切的团队来说，这是一个真正的硬件和成本限制。

最后，smolagents 不是 LangGraph 意义上的工作流编排工具。如果您的用例需要显式的分支逻辑（基于分类器将任务 A 路由到子代理 X，将任务 B 路由到子代理 Y）、具有状态持久性的条件重试或人在回路的审批步骤，LangGraph 为您提供了这些原语。smolagents 将它们抽象化了，这是它在简单用例中的优势，也是在复杂用例中的天花板。已经超越自动 ReAct 循环并需要精确编排控制的团队，应将 smolagents 视为迁移到更显式框架（如 LangGraph 或 CrewAI）之前的原型设计阶段。