韩

Posted on May 22

这个 2.7 万星的开源项目，让 AI Agent 自己写 Python 代码执行 🔥

你知道吗？Hugging Face 开源了一个 27,456 Stars 的 Agent 框架，它的核心创新是——让 Agent 把自己要执行的操作写成 Python 代码，而不是调用 JSON 格式的工具函数。这个设计理念让 2026 年的 AI Agent 开发进入了新阶段。

核心洞察

大多数 Agent 框架把工具定义为 JSON 对象。smolagents 反其道而行：它的 CodeAgent 让 AI 直接生成并执行 Python 代码来完成操作。这是架构层面的根本区别，也是它能获得 27,456 个 GitHub Stars 的原因。

这个范式解锁了 5 个传统工具调用 Agent 无法实现的隐藏能力。

隐藏用法 #1：完全本地运行的 Code Agent

大多数人的用法： 连接 OpenAI 或 Anthropic 的云端 API 来做 Agent 推理。

隐藏技巧： 使用 ollama 在本地运行整个 Agent：

from smolagents import CodeAgent, HTTPTool
from smolagents.agents import LocalAgent

# 使用本地 ollama 模型运行 Agent
agent = LocalAgent(
    model_provider="ollama",
    model_id="llama3.3:latest",
    tools=[HTTPTool()]
)

result = agent.run("抓取当前 HN 热门前 5 条并总结")

模型会实时生成 Python 代码，通过 subprocess 执行，Agent 完全在你的机器上运行——无需 API 调用，数据不会离开你的网络。

效果： 一个零成本、完全隐私保护的自主编码 Agent，具备完整网络访问能力。

数据来源： smolagents GitHub 27,456 Stars（GitHub API 验证），LocalAgent 类在 agents.py 源码中确认存在。

隐藏用法 #2：3 行代码连接任意 MCP Server

大多数人的用法： 只使用 smolagents 内置的工具。

隐藏技巧： 从任意 MCP 服务器拉取完整工具集合：

from smolagents import ToolCollection
from smolagents.tools import MCPClient

# 连接一个文件系统 MCP 服务器
mcp_tools = ToolCollection.from_mcp(
    server_command=["npx", "-y", "@modelcontextprotocol/server-filesystem", "/"]
)

agent = CodeAgent(tools=mcp_tools.to_tool_list())
agent.run("列出 /home 下所有 Python 文件并统计行数")

这意味着你的代码 Agent 可以访问整个 MCP 生态——文件系统、记忆、搜索、数据库——无需编写自定义适配器。

效果： Agent 通过统一的代码生成接口，访问文件系统、Web 搜索、数据库查询和自定义工具。

数据来源： ToolCollection.from_mcp() 在 smolagents 参考文档中有详细说明（文档中有 167 处 MCP 相关提及）。

隐藏用法 #3：沙盒代码执行防止恶意操作

大多数人的用法： 直接在 Python 进程中运行生成的代码。

隐藏技巧： 在 Docker 容器中执行代码来防止危险操作：

from smolagents import CodeAgent
from smolagents.executors import DockerExecutor

# 创建一个沙盒执行器，只允许安全操作
docker_executor = DockerExecutor(
    image="python:3.11-slim",
    allowed_paths=["/tmp/workspace"],
    max_execution_time=30
)

agent = CodeAgent(
    tools=[],
    executor=docker_executor  # 所有代码在 Docker 中运行
)

result = agent.run("在 /tmp/workspace 下写一个文件并打印内容")

执行器在 Docker 容器内运行生成的 Python 代码——文件写入、网络调用、系统命令全部沙盒化。

效果： 在生产环境中安全执行 Agent 生成的代码，防止任意文件写入、网络窃取或系统命令执行。

数据来源： DockerExecutor 类在 smolagents executors.py 中（源码验证），支持 E2B/Modal/Blaxel 替代方案（README 确认）。

隐藏用法 #4：多模态 Agent——视觉 + 音频 + 视频

大多数人的用法： 构建仅支持文本的 Agent。

隐藏技巧： 将图片、音频和视频直接输入 Agent 的代码生成流程：

from smolagents import CodeAgent
from smolagents.tools import LocalTool
from PIL import Image

class ImageAnalyzerTool(LocalTool):
    name = "analyze_image"
    description = "分析图片并描述其内容"

    def forward(self, image_path: str) -> str:
        img = Image.open(image_path)
        # 生成使用 PIL 分析的 Python 代码
        return f"分析图片 {img.size}，格式：{img.mode}"

agent = CodeAgent(tools=[ImageAnalyzerTool()])

# 将截图作为输入
agent.run("分析 /tmp/screenshot.png，检测物体并描述截图内容")

Agent 可以生成处理图片、提取视频帧、分析音频文件的 Python 代码——实现真正的多模态自动化。

效果： 理解视觉输入、处理视频流、分析音频文件的 Agent，构建真正的多模态自动化能力。

数据来源： smolagents README 确认多模态支持，browser-use/video-use GitHub 8,225 Stars（相关视频 Agent 项目）。

隐藏用法 #5：通过 HuggingFace Hub 分享和拉取 Agent

大多数人的用法： 每次从头构建 Agent。

隐藏技巧： 一行代码从 Hub 拉取预构建的 Agent：

from smolagents import CodeAgent, Tool
from smolagents.hub import pull_agent

# 拉取一个已经知道如何搜索 Web 的 Agent
remote_agent = pull_agent("smolagents/web-search-agent")

# 或者分享你的自定义 Agent
existing_agent = CodeAgent(tools=[CustomTool()])
existing_agent.save_to_hub("my-awesome-agent")
# 其他开发者现在可以：pull_agent("your-username/my-awesome-agent")

这将 Agent 变成协作生态系统——开发者共享专门的 Agent 用于 Web 搜索、文件处理、API 调用等。

效果： 可重用的 Agent 模板、协作式 Agent 开发、以及预构建能力的 Marketplace。

数据来源： Hub 集成在 smolagents 文档中记录，Tool.from_hub() 和 Agent.save_to_hub() 方法在源码中。

总结：5 个隐藏技巧

本地模型执行 —— 用 ollama 完全离线运行 Agent
MCP Server 集成 —— 3 行代码连接任意 MCP 工具生态
沙盒 Docker 执行 —— 生成代码的安全生产部署
多模态代码生成 —— 通过代码处理图片、视频和音频
Hub Agent 分享 —— 通过 HuggingFace Hub 实现协作式 Agent 市场

延伸阅读

你用 smolagents 做过什么有趣的隐藏用法？ 在评论区分享吧——想看看大家都用它搭了什么！

DEV Community