← Frameworks

模型与开放条件Model & openness

官方自述 model-agnostic："supports any LLM"（README 原文）。

实现是多套 Model 类，各管一端：

• HF 侧 InferenceClientModel 走 Hub 的 Inference Providers。官方点名这些： Cerebras、Cohere、Fal、Fireworks、HF-Inference、Hyperbolic、Nebius、 Novita、Replicate、SambaNova、Together

• 其余走 LiteLLMModel（官方称 "100+ different models"）、OpenAIModel（OpenAI 及兼容端点， 示例给 Together / OpenRouter）、AzureOpenAIModel、AmazonBedrockModel

• 本地侧有 TransformersModel、MLXModel、Ollama

换 provider 的改动量 = 换一个 Model 类。也可加 provider= 参数。代码结构不变。

未知：换 provider 后 tool calling / 结构化输出的可靠性对齐，官方未说明。 （已查 guided_tour 与 models 参考页。）

The official self-description is model-agnostic: "supports any LLM" (README, verbatim).

The implementation is several Model classes, each covering one end:

• On the HF side, InferenceClientModel goes through the Hub's Inference Providers. Officially named: Cerebras, Cohere, Fal, Fireworks, HF-Inference, Hyperbolic, Nebius, Novita, Replicate, SambaNova, Together

• The rest go through LiteLLMModel (officially "100+ different models"), OpenAIModel (OpenAI and compatible endpoints, examples given for Together / OpenRouter), AzureOpenAIModel, AmazonBedrockModel

• On the local side: TransformersModel, MLXModel, Ollama

Switching providers = swap one Model class. A provider= parameter also works. The code structure stays the same.

Unknown: after switching providers, the reliability alignment of tool calling / structured output is not stated by the official docs. (guided_tour and the models reference page checked.)

运行位置Where it runs

纯 Python 库。agent loop 由你自己在本地进程里跑。官方无托管执行服务。

官方定位原话（README）：

官方原文："run powerful agents in a few lines of code"

安装 pip install smolagents（Python ≥3.10）。 自带两个 CLI：smolagent（通用多步 CodeAgent，可交互式向导）与 webagent（基于 helium 的网页浏览 agent）。

分层多 agent 用 managed_agents= 表达委派。

它也可以把整包 agent 用 agent.push_to_hub() 作为 Gradio Space 分享到 HF Hub （README 原文 "share your agent to the Hub, as a Space repository"）。

但那只是分享 / 加载形态，不是厂商托管的常驻运行时 —— 进程仍在你自己手里。

A pure Python library. You run the agent loop yourself in a local process. No hosted execution service officially.

The official positioning, verbatim (README):

Official wording: "run powerful agents in a few lines of code"

Install pip install smolagents (Python ≥3.10). It ships two CLIs: smolagent (general multi-step CodeAgent, with an interactive wizard) and webagent (a helium-based web-browsing agent).

Hierarchical multi-agent systems are expressed with managed_agents= for delegation.

The whole agent can also be shared to HF Hub as a Gradio Space via agent.push_to_hub() (README, verbatim: "share your agent to the Hub, as a Space repository").

But that is only a share / load form — not a vendor-hosted resident runtime — the process stays in your hands.

本地文件Local files

框架本身不预置文件系统工具。

官方 default toolbox（smolagents[toolkit]）只有三项：DuckDuckGo/WebSearch、 Python 代码解释器、Whisper 转写 —— 没有专门的文件读写工具。

CodeAgent 要读写文件。它靠的是自己生成的 Python 代码（如 open()）或你提供的自定义工具。

所以文件边界由执行环境决定，框架不提供。本地跑则受 LocalPythonExecutor 的 import 白名单约束。远程沙箱跑则限在沙箱容器内。两种沙箱模式见 secure_code_execution 页。

未知：CodeAgent 默认允许的文件访问范围，官方未说明。 （已查 secure_code_execution 与 guided_tour 两页，无文件权限章节。）

The framework itself presets no file-system tools.

The official default toolbox (smolagents[toolkit]) has only three items: DuckDuckGo/WebSearch, a Python code interpreter, Whisper transcription — no dedicated file read/write tool.

CodeAgent reads and writes files through the Python code it generates itself (e.g. open()) or custom tools you provide.

So the file boundary comes from the execution environment, not the framework. Locally it is constrained by LocalPythonExecutor's import allowlist. In a remote sandbox it is confined to the sandbox container. The two sandbox modes are on the secure_code_execution page.

Unknown: the default file-access scope allowed for CodeAgent is not stated by the official docs. (secure_code_execution and guided_tour pages checked; no file-permission section.)

关机后的任务Tasks after shutdown

自托管 = 进程关了就停，无托管后台选项。

README 的运行方式全是本地代码调用。形式是 Python API / CLI / 沙箱。它没有云端常驻或定时执行形态。

唯一与「长任务 / 断点」相关的官方机制是单步执行。agent.step(memory_step) 可一次只走一步。 memory 存在进程内的 agent.memory。tutorials/memory 页举的用例正是：

官方原文："tool calls that take days"

未知：官方未提供把这些 memory 落盘并在新进程恢复的内建方案（已查 tutorials/memory 与 guided_tour 两页）。

所以断点续跑要自己序列化 steps。

Self-hosted = stop the process and it's gone; no hosted background option.

All run modes in the README are local code calls. The forms are Python API / CLI / sandbox. There is no cloud-resident or scheduled-execution form.

The only official mechanism related to "long tasks / checkpoints" is single-step execution. agent.step(memory_step) advances one step at a time. Memory lives in-process at agent.memory. The use case on the tutorials/memory page is exactly:

Official wording: "tool calls that take days"

Unknown: the official docs provide no built-in way to persist this memory and restore it in a new process (tutorials/memory and guided_tour pages checked).

So resuming after interruption means serializing steps yourself.

工具与扩展Tools & extensions

工具面很宽，而且 MCP 是一等接入。 README 自述 "Tool-agnostic"，工具共四个来源：

• ① 自定义工具 —— @tool 装饰器或继承 Tool 类
• ② MCP —— ToolCollection.from_mcp(...) 可读任意 MCP server（装 smolagents[mcp]）
• ③ LangChain 工具 —— Tool.from_langchain
• ④ 把 HF Hub Space 当工具 —— Tool.from_space

default toolbox（smolagents[toolkit]）= DuckDuckGo/WebSearch、Python 代码解释器、Whisper 转写。

多 agent 则用 managed_agents= 把子 agent 当作可调用单元。 此外有 final_answer_checks 自定义终止校验。

The tool surface is wide, and MCP is first-class access. The README self-describes as "Tool-agnostic", with four tool sources:

• ① Custom tools — the @tool decorator or subclassing Tool
• ② MCP — ToolCollection.from_mcp(...) reads any MCP server (install smolagents[mcp])
• ③ LangChain tools — Tool.from_langchain
• ④ HF Hub Spaces as tools — Tool.from_space

The default toolbox (smolagents[toolkit]) = DuckDuckGo/WebSearch, Python code interpreter, Whisper transcription.

Multi-agent systems use managed_agents= to treat sub-agents as callable units. There are also final_answer_checks for custom termination validation.

上下文与记忆Context & memory

上下文 = 步历史（AgentMemory），没有跨会话持久化。

官方 tutorials/memory 页的说法是：

agent "has a memory of past steps"

步类型分 TaskStep / ActionStep / PlanningStep / FinalAnswerStep。

可操作手段官方给了三样：

• agent.replay() 回放
• 直接读写 agent.memory.steps（示例甚至在两个 agent 间搬 steps）
• step_callbacks（官方示例：删掉旧截图以省 token）

另有 planning_interval=N 每 N 步插一次规划步。

官方把这一轴定位成「检查 / 改写记忆」，不是压缩。

未知：把大工具输出落盘这类深上下文管理，官方未说明。 （已查 tutorials/memory 与 guided_tour 两页。）

Context = the step history (AgentMemory); no cross-session persistence.

The official tutorials/memory page says the agent "has a memory of past steps".

Step types: TaskStep / ActionStep / PlanningStep / FinalAnswerStep.

Three official manipulation options:

• agent.replay() to replay
• read/write agent.memory.steps directly (the example even moves steps between two agents)
• step_callbacks (official example: delete old screenshots to save tokens)

There is also planning_interval=N to insert a planning step every N steps.

The official docs position this axis as "inspect / rewrite memory", not compression.

Unknown: deep context management like spilling large tool outputs to disk is not stated by the official docs. (tutorials/memory and guided_tour pages checked.)

权限与限制Permissions & limits

官方对执行安全说得非常直白。默认的 LocalPythonExecutor 不是安全沙箱。

README 原文：

"The built-in LocalPythonExecutor is not a security sandbox. It applies some restrictions but can be bypassed and must not be used as a security boundary."

本地解释器给的机制：

• AST 逐步执行
• import 默认禁止（用 additional_authorized_imports 开白名单）
• 子模块默认禁止（numpy.* 才放行全部子包）
• 循环迭代次数上限
• 未定义操作直接报错

要真正隔离必须用远程沙箱：executor_type="blaxel" / "e2b" / "modal" / "docker"。

官方区分两种模式。一是只沙箱化代码片段。二是整包 agent 进沙箱（后者多 agent 才可用）。

官方另有 Human-in-the-Loop 示例（examples/plan_customization），但不是内建审批机制。

未知：网络访问控制，官方未说明。

The official docs are very blunt about execution safety. The default LocalPythonExecutor is not a secure sandbox.

README, verbatim:

"The built-in LocalPythonExecutor is not a security sandbox. It applies some restrictions but can be bypassed and must not be used as a security boundary."

What the local interpreter provides:

• step-by-step AST execution
• imports denied by default (open an allowlist with additional_authorized_imports)
• submodules denied by default (numpy.* to allow all subpackages)
• loop iteration caps
• undefined operations error out

For real isolation you must use a remote sandbox: executor_type="blaxel" / "e2b" / "modal" / "docker".

The official docs distinguish two modes: sandbox only the code snippets; or put the whole agent in the sandbox (the latter required for multi-agent).

There is also a Human-in-the-Loop example (examples/plan_customization), but it is not a built-in approval mechanism.

Unknown: network access control is not stated by the official docs.

适合什么任务Best for

适合这四类场景。

• 认同 code-as-action（官方称比 JSON 工具调用少 30% 步数），并愿意给 LLM 生成代码上沙箱
• 要 model-agnostic、能接本地模型（transformers / Ollama / mlx-lm）
• 要薄而可 hack 的库；Python 栈
• 要 MCP / LangChain / Hub Space 工具生态

不适合这三类场景。

• 需要厂商托管的常驻后台或断点续跑（纯库，memory 不落盘）
• 既不想承担任意代码执行风险、又不想上远程沙箱
• 要 batteries-included 的预置文件系统 / 记忆 / 子代理编排

Fits these four scenarios.

• You buy into code-as-action (officially "30% fewer steps" than JSON tool calling) and are willing to sandbox LLM-generated code
• You want model-agnostic access including local models (transformers / Ollama / mlx-lm)
• You want a thin, hackable library; Python stack
• You want the MCP / LangChain / Hub Space tool ecosystem

Does not fit these three scenarios.

• You need a vendor-hosted resident background or checkpoint resume (pure library; memory is not persisted)
• You want neither arbitrary-code-execution risk nor a remote sandbox
• You want batteries-included preset file system / memory / sub-agent orchestration

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.