smolagents：HuggingFace 开源的千行代码 AI 智能体框架

HuggingFace 开源的智能体框架 smolagents，目前在 GitHub 拿下了 27,944 颗 Star。

smolagents 是一个轻量级的 Python 库，用不到 1000 行核心代码就能跑起 AI 智能体。

它最大的特点是 Code Agent 模式：智能体直接生成 Python 代码来执行操作，而不是像传统方案那样输出 JSON 格式的工具调用指令。实测数据表明，这种方式比传统做法少走 30% 的步骤，同时在高难度基准测试上的得分更高。

模型和工具的支持范围

smolagents 对模型没有限制。你可以接入 HuggingFace Hub 上的推理服务，也可以用 OpenAI、Anthropic 等主流厂商的模型，还能跑本地的 transformers 或 ollama 模型。甚至 Azure 和 Amazon Bedrock 的模型也能直接用。

工具方面同样灵活。它支持从 MCP 服务器导入工具，也能把 LangChain 的工具或 HuggingFace Space 当作工具来调用。

输入也不局限于文本。图片、视频、音频都能处理。

几行代码就能跑起来

安装：

pip install "smolagents[toolkit]"

用 InferenceClientModel 跑一个简单的例子：

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

切换到其他模型也简单。比如用 LiteLLM 接 Anthropic 的 Claude：

from smolagents import LiteLLMModel

model = LiteLLMModel(
    model_id="anthropic/claude-4-sonnet-latest",
    temperature=0.2,
    api_key=os.environ["ANTHROPIC_API_KEY"]
)

或者用本地的 transformers 模型：

from smolagents import TransformersModel

model = TransformersModel(
    model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
    max_new_tokens=4096,
    device_map="auto"
)

想把自己的智能体分享给别人，一行代码推到 HuggingFace Hub 就行。

命令行也能用

smolagents 提供了两个 CLI 工具。smolagent 是通用的多步智能体，webagent 专门用于网页浏览。

直接在命令行里跑：

smolagent "帮我规划 3 月 28 日到 4 月 7 日的东京、京都、大阪旅行" --model-type "InferenceClientModel" --model-id "Qwen/Qwen3-Next-80B-A3B-Thinking" --imports pandas numpy --tools web_search

不带参数运行 smolagent 会进入交互模式，引导你选择智能体类型、工具、模型等配置。

安全机制

代码执行需要在沙箱环境里跑。smolagents 支持 E2B、Blaxel、Modal 这类托管云沙箱，也支持 Docker 自行部署。内置的 LocalPythonExecutor 有一定限制，但不能作为安全边界，不建议用来跑不信任的代码。

基准测试结论

官方用多个模型跑了 Code Agent 基准测试。结果显示，开源模型 DeepSeek-R1 在代码智能体模式下的表现接近甚至超过了部分闭源模型。同时，用代码方式写行动的智能体比传统的 JSON 工具调用方式少用大约 30% 的步骤。

型 DeepSeek-R1 在代码智能体模式下的表现接近甚至超过了部分闭源模型。同时，用代码方式写行动的智能体比传统的 JSON 工具调用方式少用大约 30% 的步骤。