smolagents 教程：Python 代码智能体原理、沙箱与框架选型

如果你的 Python 智能体需要灵活组合工具与计算步骤，而且你能为生成的代码提供受控的运行环境，smolagents 就值得考虑。Hugging Face 提供了 2 种智能体类：CodeAgent 和 ToolCallingAgent。两者的区别在于，模型是用 Python 表达下一步动作，还是发出结构化工具调用。精简的设计适合解决边界明确的问题，但工作流持久化、权限控制和执行隔离，仍需要你自己负责。

本文已于 2026 年 10 月 31 日对照 Hugging Face、LangChain 和 OpenAI 的在线文档核实。 下文从动作组合、工作流控制和执行边界三个方面给出选型建议。这些建议是架构层面的判断，并非性能基准测试结论。

smolagents 如何用 Python 驱动智能体？

smolagents 是 Hugging Face 的开源 Python 库，用于构建以可执行代码作为动作的智能体。 智能体的核心是一个由模型驱动的循环：选择动作、观察执行结果，再决定下一步。CodeAgent 用 Python 表达动作，ToolCallingAgent 则采用结构化工具调用。两者都需要接入模型和工具集。参见 Hugging Face 智能体参考文档。

可以把 CodeAgent 理解成一名研究员：每次获得新信息后，都可以写一小段脚本继续处理。它可以通过获准使用的工具查询记录，转换返回的数据，再计算答案。你负责提供能力、设定约束，模型则负责把这些能力连接起来。

这与生成代码文件、交给你审阅的编程助手有所不同。在这里，生成代码本身就是智能体采取下一步动作的方式。

比较框架时，关键是看应用的哪个环节需要灵活性：

后两行概括的是 LangGraph 和 OpenAI Agents SDK 文档强调的重点，并不表示这些能力为其独有。选择哪一个，取决于你希望框架在哪个环节提供结构化支持。

smolagents CodeAgent：让模型组合执行动作

如果中间处理过程用 Python 比用一套固定调用更容易表达，CodeAgent 就有了用武之地。 Hugging Face 文档将循环、条件判断和工具组合列为它的优势，同时也指出，需要处理语法错误、异常和意外行为。参见功能导览。

例如，开发者正在排查不一致的库存记录。只读查询工具先返回候选记录，智能体可能需要统一名称格式、把相似条目分组、对某个字段求和，再判断哪些记录需要进一步查询。Python 很适合表达这些中间步骤。

执行结果会成为模型做下一次判断的依据。计算失败也是智能体可以据此调整的观察结果，但这不代表它一定能自行修复问题。

ToolCallingAgent：把动作限定在明确的工具范围内

如果各项操作已经有清晰的接口约定，通常更适合从 ToolCallingAgent 入手。 它生成包含工具名和参数的结构化 JSON 调用，而不是生成 Python 动作代码。参见 Hugging Face 的对比说明。

客服助手如果只需要查订单、取政策说明，这种方式可能已经足够。可预期的数据转换交给普通应用代码即可。当流程本就能清晰地拆成函数时，再引入生成式 Python，只会多出一种故障来源，却未必带来明确收益。

结构化调用同样需要授权检查。取消订单的请求即使格式正确，也可能不适用于当前客户。Schema 只能告诉程序请求了什么；是否允许执行，要由应用判断。

工具和模型，应该分开选择

工具集保持精简，模型则独立选型。 这正是 smolagents 的实用之处：你可以调整智能体的推理方式，而不必重新定义每项业务能力。

工具：为函数提供清晰可用的接口约定

smolagents 工具是在函数外封装名称、描述、输入元数据和输出类型。带有类型提示和清晰文档字符串的简单函数，适合用 @tool 装饰器；工具更复杂时，可以继承 Tool，把执行逻辑写在 forward 中。参见工具指南。

对于库存助手，应提供“在获准访问的目录中查询记录”这样的具体能力，而不是开放不受限制的数据库访问。租户检查、查询约束和返回结果上限，都应落实在工具实现里。提示词写得再有说服力，也不能代替这些检查。

工具还可以来自 Model Context Protocol（MCP），这是一种向模型应用开放工具的标准接口；也可以通过适配器接入 LangChain 工具和 Hugging Face Spaces。能够复用一个工具，并不代表它的实现值得信任。Hugging Face 明确要求，加载 Hub 工具时必须设置 trust_remote_code=True，因为这些工具会运行自定义代码。参见工具集成与加载文档。

是否信任这段代码，应通过代码审查来判断。把工具交给智能体之前，先检查它的实现和依赖。

模型后端不决定沙箱边界

当前模型参考文档列出了几种接入方式：

• InferenceClientModel：通过 Hugging Face Inference Providers 连接模型。
• LiteLLMModel：使用 LiteLLM 的模型服务商集成层。
• TransformersModel：在本地运行 Transformers 模型。
• OpenAIModel：连接兼容 OpenAI 接口的模型服务器。

功能导览还介绍了通过 Ollama 进行本地推理。这些只是后端选项，不代表每个模型在代码生成和工具选择上都同样可靠。

要分清两个问题：模型在哪里运行，模型生成的 Python 又在哪里运行？托管模型可以驱动 Docker 执行器，本地模型也可能生成不安全的动作。把推理搬到自己的机器上，并不等于建立了执行隔离边界。

演示之后若要获得可复现的结果，应显式配置模型。Hugging Face 提醒，InferenceClientModel 的默认模型可能发生变化。参见模型配置说明。

smolagents 教程：从文档中的小例子看执行流程

先用文档里的算术任务看懂执行路径，再添加工具。 Hugging Face 的入门示例让智能体在工具集为空的情况下，计算 1 到 10 的总和。下面保留这一任务，并加入沙箱指南中的 Docker 上下文管理器用法。参见原始示例和 Docker 执行配置。

1. 1

   准备运行环境

   安装指南要求 Python 3.10 或更高版本，并建议使用虚拟环境。运行这个例子还需要先安装并启动 Docker。参见安装指南。

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   在环境变量 HF_TOKEN 中设置有权调用 Inference Providers 的 Hugging Face 令牌。InferenceClientModel 可以自动读取这个变量。不要把令牌写进脚本。参见认证机制说明。

2. 2

   在 Docker 中运行文档示例任务

   将以下代码保存为 sum_agent.py：

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   然后运行：

   python sum_agent.py

   退出代码块时，上下文管理器会负责清理沙箱。这个例子改编自官方文档，本文并未实际运行测试，也没有将它作为实测结果。

3. 3

   检查计算结果与执行边界

   数学上的预期答案是 55，计算式为 10 × 11 ÷ 2。具体生成哪段 Python 由模型决定，因此不要预期每次运行都有完全一致的过程记录或措辞。

   tools=[] 表示没有提供自定义工具，不代表 CodeAgent 不能执行 Python。真正将生成代码放进 Docker 运行的是执行器配置。

对于这个固定计算，直接写普通 Python 才是合理的应用实现。这里用它来展示智能体的工作机制。只有当“如何选择中间步骤”本身就是问题的一部分时，才有必要引入智能体；不能仅因为一个计算任务可以用自然语言描述，就为它加上智能体。

执行代码的智能体，需要明确的沙箱边界

将生成的 Python 视为不可信代码；在它接触不可信输入之前，先配置明确的沙箱。 默认本地执行器是受限解释器，并不保证宿主机已被隔离。Hugging Face 将模型错误、提示词注入和恶意请求列为风险。参见安全代码执行指南。

本地解释器会逐项执行 Python 抽象语法树，也就是程序解析后的结构。它限制导入和子模块访问，并设置操作次数上限。这些控制可以降低风险暴露，但专门的安全指南仍提醒，本地执行存在风险。每多授权一个包，生成程序能够触及的范围就会扩大。

Hugging Face 支持哪些沙箱？

除本地执行器外，当前执行器 API 还支持 Blaxel、E2B、Modal 和 Docker。 下表中的配置名称与 CodeAgent 参考文档及执行器参考文档一致。

服务商和凭据需要在这些配置之外另行选择与设置。安装文档列出了可选依赖，但仅安装扩展依赖，并不等于完成部署配置。

对于内部实验，Docker 可以提供一个具体、可检查的执行边界。对于处理不可信请求的服务，则应根据所需的隔离能力、生命周期管理和运维控制来选择环境。AI 智能体代码沙箱对比进一步讨论了这项基础设施决策。

代码片段进沙箱，不等于整个智能体进沙箱

增加更多智能体之前，先确定隔离边界内究竟要放什么。 Hugging Face 区分了两种做法：只在沙箱里运行生成的代码片段，或把整个智能体系统放进去。安全指南提醒，仅隔离代码片段的方式不支持受管理智能体（managed agents），也就是被其他智能体调用、协助完成任务的智能体。将整个系统移入沙箱需要更多配置，也可能需要提供凭据。参见沙箱部署方式。

这会影响架构设计。未来如果某个专职智能体需要在执行环境内部调用模型，原先“发送代码、接收结果”的安排可能就不够了。调整部署方式时，应重新检查凭据存放位置和工具依赖。

面向客户的服务，应在智能体启动前明确允许访问的文件、网络目标和可调用操作。每次运行只授予完成任务所需的权限。将超时、取消和清理纳入正常执行流程，包括模型未能完成任务的情况。

AI 智能体框架选型：什么时候适合精简方案？

围绕应用中最难解决的控制问题选择框架。 初始化代码短固然方便，但更值得关注的是，你还要在它周围补上多少代码。

smolagents 与 LangGraph：动态动作，还是持久化流程控制？

如果业务流程需要围绕明确的状态持久保存、暂停和恢复，通常更适合从 LangGraph 入手。 它是面向有状态工作流的底层编排运行时，支持持久化和人工介入。它可以混合确定性步骤与模型驱动步骤，也不要求使用 LangChain。参见 LangGraph 概览。

设想一个采购流程：收集依据，等待经理审批，获批后继续执行。核心问题是保存流程状态，并确保每次流转都符合规则。如果这些要求决定了产品形态，就应优先考虑 LangGraph。

代价是工作流设计需要你自己负责：状态、状态转换、持久化，以及某一步重试时究竟意味着什么。对采购流程而言，这些投入有价值；但对于读取数据、计算答案后就停止的有限范围研究助手，这套结构可能并无必要。

如果主要的不确定性在于哪些 Python 操作能解决任务，选择 smolagents；如果主要的不确定性在于流程如何在持久化状态之间安全推进，选择 LangGraph。这是设计建议，不代表任一框架只能处理某一类任务。

OpenAI Agents SDK：智能体交接、检查与追踪

如果应用的核心是专职智能体协作和运行检查，OpenAI Agents SDK 通常更适合作为默认选择。 它的 handoffs 机制将对话主导权移交给另一个智能体；agents-as-tools 模式则让管理智能体继续对最终回复负责。参见编排文档。

对于客服助手，让账单专员接手对话，可能比交给通用 Python 问题求解器更容易表达业务职责。内置追踪会记录模型调用、工具调用、交接和护栏检查。护栏负责自动检查，人工审核机制则会暂停敏感操作，等待决策。参见追踪说明及护栏与审核。

你仍需负责应用策略：哪些操作需要审批、如何正确实现工具、如何处理被中断的任务。这些基础能力不会替你制定策略。SDK 文档也介绍了沙箱智能体模式，因此代码执行并非 smolagents 独有。

如果你需要的正是 Python 动作组合，而且一个小型循环就足够，可以优先选择 smolagents。如果 Agents SDK 的协作与审核能力更贴合应用需求，就选择它。仅凭“轻量”二字，无法完成这项比较。

要比较更多候选方案，可以阅读 AI 智能体框架对比。如果你想安装现成的智能体应用，而不是围绕代码库自行开发，可以从开源 AI 智能体指南看起。

代码智能体有哪些被夸大的地方？

框架小，不会让不可预测的任务变得可预测。 Python 的表达能力很有用，但它无法保证模型选对了记录、理解对了单位，或遵守了业务规则。

也不要把可组合性直接等同于普遍的速度优势。合并操作可以改变一次运行的执行方式，但结果仍由模型、任务、工具行为和执行环境共同决定。若要按性能选型，先测量自己的实际任务。

还有一项具体限制需要理解：当前智能体 API 中，max_steps 的默认值为 20。它限制的是智能体步数，而不是单个 Python 动作消耗的资源。API 也提供回调、受管理智能体和最终答案检查，因此精简不等于缺少控制能力。参见智能体参考文档。

落到运行管理上，执行时长和资源上限必须单独设置。步数上限不能代替沙箱策略，沙箱也不能保证结果正确。

下周可以从什么任务开始？

先选一个边界明确、只读、答案可以独立核验的任务。 评估 smolagents 的 Python 开发者，可以准备一份脱敏的库存导出数据和一个权限范围受限的查询工具，再把智能体找出的异常与已知样例进行比较。

记录它是否选对记录、正确使用工具、从预期故障中恢复，并在设定的限制内停止。保留确定性实现作为基线。如果任务始终沿着同一条路径执行，就把这条路径写成普通代码；Hugging Face 自己也建议，能用确定性函数的地方就尽量使用。参见构建可靠智能体指南。

只有当动态组合 Python 带来的收益值得承担额外复杂度时，再推进 CodeAgent。明确的工具列表已经够用，就选择 ToolCallingAgent。现有工作流已经满足需求，则不必急于迁移。等到持久化审批或专职智能体交接成为核心要求时，再重新评估框架选择。

安装与兼容性常见问题

如何用 pip 安装 smolagents？

使用 pip install smolagents 安装核心库，再按工具、模型或执行环境的需要添加扩展依赖。本文示例使用 smolagents[docker]。

smolagents 新代码还应使用 HfApiModel 吗？

新代码应遵循当前文档，使用 InferenceClientModel 接口。复制旧示例的导入语句之前，先对照在线模型参考文档检查。

smolagents 如何配置 Docker？

安装并启动 Docker，安装 Docker 扩展依赖，然后设置 executor_type="docker"。还要根据实际工作负载配置执行边界；这一项设置并不构成完整的安全策略。

订阅邮件通讯，获取实用的 AI 开发笔记。