← Harness

模型与开放条件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 参考页。）

运行位置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"）。

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

本地文件Local files

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

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

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

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

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

关机后的任务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。

工具与扩展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 自定义终止校验。

上下文与记忆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 两页。）

权限与限制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），但不是内建审批机制。

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

适合什么任务Best for

适合这四类场景。

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

不适合这三类场景。

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

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