大多数 Agent 框架让模型去"选一个函数"，而 Hugging Face 的 smolagents 走了一条更直接的路：让模型直接写 Python 代码来解决问题，然后在沙箱里执行。这种 "Code Agent" 特别适合数据分析、批量处理、需要多步逻辑组合的任务。本教程从装包到多 Agent 协作，全程可复制粘贴跑通。
先搞懂：Code Agent 和普通工具调用有什么不同？
用一句话理解：普通 Agent 像"填空题"——模型只能从你给的几个固定函数里挑；Code Agent 像"应用题"——模型自己写一小段 Python 把多个工具串起来。比如"比较北京和东京天气"，Code Agent 会写出 w_bj = get_weather("北京"); w_tk = get_weather("东京") 再比较，而不需要你预先定义好"对比天气"这个函数。
| 方式 | 模型产出 | 适合场景 |
|---|---|---|
| 函数调用 Agent | 选一个已定义函数 + 参数 | 动作固定的流程 |
| Code Agent | 写 Python 代码并运行 | 需要组合/计算/多步逻辑 |
Step 1：安装 smolagents
pip install smolagentspip install 'smolagents[toolkit]'，或在初始化 Agent 时设 add_base_tools=True。新手先用最小安装，理解原理。Step 2：用 @tool 写第一个工具
任何 Python 函数，只要加上 @tool 装饰器、写好类型注解和带 Args: 的 docstring，就能被 Agent 调用。docstring 就是 Agent 的"使用说明书"，写得越清楚越好。
from smolagents import tool
@tool
def get_weather(city: str) -> str:
"""获取城市当前天气。
Args:
city: 城市名，例如 北京
Returns:
天气描述字符串
"""
# 实际项目里这里接真实天气 API；示例返回固定文本
return f"{city}：晴，22°C"docstring 的 Args 段不能省。Agent 完全靠它理解参数含义和类型；省略或含糊，模型很容易传错参数导致工具调用失败。输出类型注解也建议写清楚。
Step 3：接一个大模型
smolagents 用 InferenceClientModel 对接 Hugging Face Inference API，默认就能跑（部分模型免 token）：
from smolagents import InferenceClientModel
model = InferenceClientModel() # 默认用 HF Inference API
# 想指定模型 / 带 token：
# model = InferenceClientModel(
# model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
# token="hf_xxxxxxxx",
# )OpenAIServerModel / LiteLLMModel / OllamaModel 即可（具体参数见 smolagents 官方文档），思路完全一致。Step 4：初始化 CodeAgent 并运行
from smolagents import CodeAgent
agent = CodeAgent(tools=[get_weather], model=model, add_base_tools=False)
result = agent.run("北京和上海现在天气分别是怎样的？")
print(result)CodeAgent 会真正执行模型生成的 Python。请在隔离/可信环境运行，不要给它写文件、访问生产数据库等危险权限；涉及敏感数据时用本地模型或企业版。生产环境建议限制 additional_authorized_imports。
Step 5：再加工具，让 Agent 自己编排
工具越多，Code Agent 越能"自编自演"把任务拆成多步：
@tool
def get_news(topic: str) -> str:
"""获取某主题的最新资讯摘要。"""
return f"关于 {topic} 的 3 条最新动态……"
agent = CodeAgent(tools=[get_weather, get_news], model=model)
print(agent.run("对比北京天气和今天 AI 领域的新闻"))Step 6：多 Agent 协作（ManagedAgent）
把某个 Agent 包成 ManagedAgent，交给"经理 Agent"调用，适合把复杂任务分层：
from smolagents import ManagedAgent
weather_agent = CodeAgent(
tools=[get_weather], model=model,
name="weather", description="查询任意城市天气",
)
manager = CodeAgent(
tools=[], model=model,
managed_agents=[weather_agent], max_steps=10,
)
manager.run("把国内主要城市的天气汇总一下")Step 7：可视化调试（GradioUI）
用官方 Gradio UI 起一个网页，能实时看到 Agent 写的代码、执行结果和最终答案，非常适合调试：
from smolagents import GradioUI
GradioUI(agent).launch()常见问题速查
| 现象 | 原因 & 解决 |
|---|---|
| 工具没被调用 | docstring 的 Args/类型写不清，重写说明书 |
| 模型报 401 | 指定了需 token 的模型却没传 token |
| 代码执行报错 | 看 GradioUI 里的代码，多半是工具返回格式对不上 |
| 任务卡住 | 调大 max_steps 或简化问题 |