smolagents

Hugging Face 的轻量 Agent 框架，CodeAgent 直接生成并执行 Python 动作。

补充说明

smolagents 用很少的抽象实现 ReAct 循环：模型每一步输出思考和一个动作，框架执行工具并把观察结果写回记忆。CodeAgent 把动作写成 Python 代码，表达力强、适合数据处理；ToolCallingAgent 用 JSON 工具调用，约束更强、对模型能力要求更低。

工具可以用 @tool 装饰普通函数，或继承 Tool 定义 name、description、inputs、output_type 和 forward。模型侧支持 InferenceClientModel、LiteLLMModel、TransformersModel 等；max_steps 默认 20，add_base_tools=True 会加入内置工具。

安全边界要特别注意：本地 Python executor 基于 AST 限制导入，不是强隔离沙箱，不能用来执行不可信代码。生产或面向用户的场景应使用 executor_type="docker"、"e2b"、"modal" 等远程执行器，并限制导入、步数和网络。

常用示例

安装基础包；需要网页搜索等工具时再装 toolkit 额外依赖：

pip install -U "smolagents[toolkit]"
export HF_TOKEN="hf_..."

用 CodeAgent 跑一个最小任务，模型通过 HF Inference 调用：

from smolagents import CodeAgent, InferenceClientModel
model = InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct")
agent = CodeAgent(tools=[], model=model, max_steps=8)
print(agent.run("计算 2 的 10 次方，并解释每一步"))

需要工具调用而不是代码执行时换 ToolCallingAgent：

from smolagents import ToolCallingAgent, WebSearchTool, InferenceClientModel
agent = ToolCallingAgent(tools=[WebSearchTool()], model=InferenceClientModel(), max_steps=8)
print(agent.run("查一下 Milvus 最新稳定版本"))

用 @tool 定义自定义工具，docstring 的 Args 会进入参数说明：

from smolagents import tool
@tool
def disk_free(path: str) -> int:
    """返回指定路径的可用字节数。

    Args:
        path: 要检查的目录路径。
    """
    import shutil
    return shutil.disk_usage(path).free

给 CodeAgent 放开必要导入，并限制步数；不要开放整个标准库：

from smolagents import CodeAgent, InferenceClientModel
agent = CodeAgent(tools=[], model=InferenceClientModel(),
                  additional_authorized_imports=["pandas", "numpy"],
                  max_steps=10)
print(agent.run("统计 data.csv 的行数"))

把代码执行放进 Docker，退出上下文时清理容器：

from smolagents import CodeAgent, InferenceClientModel
with CodeAgent(tools=[], model=InferenceClientModel(), executor_type="docker") as agent:
    print(agent.run("列出当前目录文件并统计数量"))

用 LiteLLM 接本地 Ollama 的 OpenAI 兼容接口：

from smolagents import CodeAgent, LiteLLMModel
model = LiteLLMModel(model_id="ollama_chat/qwen2.5-coder:7b", api_base="http://localhost:11434")
agent = CodeAgent(tools=[], model=model, max_steps=6)
print(agent.run("写一个检查磁盘使用率的 Python 片段"))

CLI 适合快速验证，--imports 和 --tools 控制能力边界：

smolagent "统计当前目录下最大的 5 个文件" \
  --model-type InferenceClientModel --model-id "Qwen/Qwen2.5-Coder-32B-Instruct" \
  --imports "os pathlib" --tools ""

查看每一步的记忆和工具结果，便于定位错误：

print(len(agent.memory.steps))
print(agent.write_memory_to_messages())

易错点与排错

本地 executor 不是安全沙箱；提示注入可以诱导代码读写文件或访问网络，不可信输入必须用 Docker/E2B 等隔离执行器。
additional_authorized_imports 只写顶层包不够，用到子模块时要显式加入；缺权限会抛 InterpreterError，而不是模型答错。
没有设置 max_steps 时默认 20，复杂任务可能提前停止；调大上限同时设置 final_answer_checks，避免无限循环。
代码执行器有操作数和输出长度限制，死循环或超大 print 会被中断；检查异常信息和 agent.memory.steps。
弱模型生成非法 Python 或虚构工具名，CodeAgent 会反复重试；换代码能力更强的模型，或改用 ToolCallingAgent。
工具函数缺少 docstring、类型注解或 Args，模型拿不到参数说明；用 @tool 时先检查生成的 schema。
Docker/E2B 需要额外依赖、镜像和网络配置；容器内没有宿主的环境变量和文件，路径要显式挂载或传入。
HF Inference 有速率限制和模型可用性限制；设置 HF_TOKEN，并在 429 时降低并发或换 provider。
push_to_hub 要求工具代码自包含，导入写在函数内部；依赖宿主全局变量的工具上传后会失败。
GradioUI 默认保留记忆，多用户场景会串上下文；设置 reset_agent_memory=True 或每个会话新建 Agent。

读完自测

CodeAgent 与 ToolCallingAgent 的核心区别是什么？
本地 Python executor 为什么仍不安全？
如何限制 CodeAgent 的导入和步数？

答案

CodeAgent 让模型生成并执行 Python 代码作为动作，表达力强但执行风险高；ToolCallingAgent 让模型输出 JSON 工具调用，约束更强、更容易审计。
它主要靠 AST 检查限制导入和操作，不是容器或虚拟机隔离；提示注入、解释器漏洞或放开的导入都可能突破限制，因此不能执行不可信代码。
用 additional_authorized_imports 只开放必要模块，设置 max_steps 限制循环，并用 executor_type="docker" 或 "e2b" 做隔离。

smolagents

补充说明

常用示例

易错点与排错

相关命令

读完自测