Smolagents（小型智能体）深度评测：2025年Hugging Face开源轻量级AI Agent框架的智能自动化利器使用教程：从入门到精通

从选型到落地的可执行指南，适合个人与团队快速上手。

教程正文

从选型到落地的实战步骤。

一、什么是Smolagents？

Smolagents是Hugging Face于2025年推出的开源轻量级AI Agent框架，专注于让开发者用最少的代码构建智能自动化流程。相比LangChain、CrewAI等重量级框架，Smolagents的核心优势在于：

极简API：仅需几行Python代码即可创建能调用工具、执行代码的Agent
原生Hugging Face集成：无缝调用Transformers、Datasets、Hub模型
安全沙箱：内置代码执行沙箱，默认禁止危险操作
多模型支持：兼容OpenAI、Claude、本地开源模型（如Llama 3、Qwen2）

本教程将带你从零开始，掌握Smolagents的安装、基础用法、高级技巧，并能独立构建实用自动化Agent。

二、环境准备与安装

2.1 系统要求

Python >= 3.9
操作系统：Linux、macOS、Windows（推荐WSL2）
建议使用虚拟环境

2.2 安装Smolagents

pip install smolagents

安装后验证：

python -c "import smolagents; print(smolagents.__version__)"

如果输出版本号（例如0.2.1）则表示成功。

2.3 配置模型

Smolagents支持多种模型后端。以Hugging Face Hub上的免费模型为例，需要设置环境变量：

export HF_TOKEN=你的Hugging Face Token

若使用OpenAI，则设置：

export OPENAI_API_KEY=你的OpenAI Key

三、快速上手：创建你的第一个Agent

3.1 编写代码

新建文件my_first_agent.py，输入以下内容：

from smolagents import CodeAgent, HfApiModel

# 使用Hugging Face的免费模型（如Qwen2.5-7B-Instruct）
model = HfApiModel("Qwen/Qwen2.5-7B-Instruct")

# 创建Agent，赋予它一个简单的工具：计算器
agent = CodeAgent(
    model=model,
    tools=[],  # 暂不添加自定义工具，Agent会自动使用代码执行能力
    add_base_tools=True  # 添加基础工具：代码执行、搜索（需联网）
)

# 运行Agent
response = agent.run("计算 123 * 456 等于多少？")
print(response)

3.2 运行结果

执行python my_first_agent.py，你会看到类似输出：

▶ Agent is starting...
▶ Running code: print(123 * 456)
56088

计算结果：56088

Agent自动生成了Python代码并执行，返回结果。这说明它已经具备了代码解释能力。

3.3 技巧：选择不同模型

如果本地有强大的模型（如Llama 3.1 70B），可以使用HfLocalModel：

from smolagents import HfLocalModel
model = HfLocalModel("meta-llama/Llama-3.1-70B-Instruct")

四、集成工具：让Agent连接外部API

4.1 内置工具库

Smolagents提供了丰富的预置工具，例如：

WebSearchTool：调用DuckDuckGo搜索
ImageGenerationTool：调用Stable Diffusion生成图片
PythonInterpreterTool：类似Jupyter的代码执行

4.2 实战：让Agent搜索并总结

from smolagents import CodeAgent, HfApiModel, WebSearchTool

model = HfApiModel("Qwen/Qwen2.5-7B-Instruct")
search_tool = WebSearchTool()

agent = CodeAgent(
    model=model,
    tools=[search_tool],
    add_base_tools=False  # 只使用我们提供的工具
)

result = agent.run("搜索Hugging Face本周最热门的模型，并用中文总结前三个")
print(result)

Agent会自动调用搜索工具获取网页内容，然后生成总结。

4.3 自定义工具

你可以通过继承Tool类创建自己的工具：

from smolagents import Tool

class WeatherTool(Tool):
    name = "weather"
    description = "获取指定城市的当前天气"
    inputs = {"city": {"type": "string", "description": "城市名称"}}
    output_type = "string"
    
    def forward(self, city: str) -> str:
        # 实际可调用OpenWeatherMap API
        return f"{city}的天气：晴天，25℃"

agent = CodeAgent(model=model, tools=[WeatherTool()])
print(agent.run("巴黎的天气怎么样？"))

五、高级功能：多Agent协作与记忆

5.1 记忆与对话

默认Agent是无状态的，但可以通过Memory模块实现上下文记忆：

from smolagents import Memory

memory = Memory()
agent = CodeAgent(model=model, memory=memory, tools=[])
agent.run("我的名字是张三")
agent.run("我叫什么名字？")  # 会回答“张三”

5.2 多Agent协作

使用Orchestrator可以编排多个Agent协同工作：

from smolagents import Orchestrator, CodeAgent

# 创建两个专业Agent
sales_agent = CodeAgent(model=model, name="销售助手", tools=[...])
tech_agent = CodeAgent(model=model, name="技术助手", tools=[...])

orchestrator = Orchestrator(
    agents=[sales_agent, tech_agent],
    plan_prompt="分析用户需求，分配给合适的Agent"
)

response = orchestrator.run("我需要开发一个聊天机器人，预算5万元")
# 销售助手会报价，技术助手会给出技术方案

5.3 安全沙箱配置

在生产环境中，建议限制Agent执行的代码权限：

agent = CodeAgent(
    model=model,
    sandbox={"allowed_imports": ["math", "json", "re"],
              "max_execution_time": 10}  # 超时10秒
)

六、最佳实践与常见问题

6.1 提示词优化技巧

通过system_prompt可以定制Agent的行为：

agent = CodeAgent(
    model=model,
    system_prompt="你是数据分析专家，只提供Python代码解决方案，并给出详细注释"
)

6.2 处理错误

Agent执行代码可能出错，使用retry参数自动重试：

agent.run("复杂任务", max_retries=3)

6.3 常见问题

Q：Agent执行太慢？ A：改用本地模型或更小模型（如Qwen2.5-1.5B），或升级硬件。
Q：工具调用失败？ A：检查API Key、网络连接，并确保工具描述准确。
Q：如何保存Agent状态？ A：使用agent.save_state()和load_state()序列化到JSON。

七、总结

Smolagents以其轻量、灵活、与Hugging Face生态深度集成等特点，成为2025年构建AI Agent的不二之选。从简单的代码执行到复杂的多Agent协作，本教程涵盖了所有核心功能。建议你立即动手尝试，并从以下方向进一步探索：

结合Gradio搭建可视化Agent界面
利用Tool.from_langchain()复用LangChain工具
部署到Hugging Face Spaces免费托管

最后，记住一条黄金法则：好的Agent = 好的模型 + 清晰的工具定义 + 合理的系统提示。祝你自动化之旅愉快！