Smolagents：读得懂的极简 Agent
你将学会什么
Section titled “你将学会什么”- 说清 CodeAgent「LLM 写代码、框架执行」的理念
- 用
@tool装饰器把一个普通函数变成工具 - 跑通一个多步执行的最小 Agent 并看懂它的日志
Smolagents 是 Hugging Face 出品的极简 Agent 框架，核心逻辑只有约一千行代码。它的理念很特别：别的框架让 LLM 输出 JSON 工具调用，它直接让 LLM「写 Python 代码」，再由框架在受控环境里执行——所以一个会算数、会循环、会组合的 Agent，代码反而最短。注意版本：2026 年模型类已改用 InferenceClientModel（旧教程里的 HfApiModel 已退役，照抄会报错）。最小的可运行例子长这样：
# 安装: pip install 'smolagents[toolkit]'from smolagents import CodeAgent, InferenceClientModel, tool
# ① @tool:函数名、类型注解、docstring 会写进 Agent 提示词,成为 LLM 的工具手册@tooldef add(a: int, b: int) -> int: """把两个整数相加。""" return a + b
# ② 模型(HF 免费额度即可;也可换 LiteLLMModel("gpt-4o") 等)model = InferenceClientModel()
# ③ 创建 CodeAgent:tools 和 model 是仅有的两个必需参数agent = CodeAgent(tools=[add], model=model)
# ④ 运行:Agent 循环「写代码 → 执行 → 看结果」,直到调用 final_answer() 为止result = agent.run("请计算 3 和 4 的和,再加 10")print(result) # 17运行日志会像「分步解答」一样展示过程：它先算出 total = add(a=3, b=4) + 10 得 17，再调用 final_answer("17") 结束——agent.run() 的返回值以 final_answer 为准，可能经历多步。
新手最常犯的错：把工具写成「没有 docstring 和类型注解的裸函数」——LLM 看不懂就不会调用它。另外，CodeAgent 的代码真的会被执行，默认禁止 import，需要 additional_authorized_imports 显式放行，别把危险包加进去跑不可信输入。
先自己回答，再看答案：
- CodeAgent 和传统「JSON 工具调用」的 Agent 有什么不同？
- 为什么工具函数的 docstring 和类型注解很重要？
agent.run()的返回值什么时候生效？
参考答案
- CodeAgent 让 LLM 直接写 Python 代码并由框架执行，表达力更强；传统方式让 LLM 输出 JSON 调用指令。
- 它们会被写进 Agent 的提示词，是 LLM 判断「这个工具干什么、怎么用」的唯一依据。
- Agent 循环直到调用 final_answer() 时才给出最终答案，可能经历多步。
- Smolagents 用「LLM 写代码 + 框架执行」的 CodeAgent 理念把代码量压到最小
@tool+ 完整 docstring 是把函数变成工具的标准姿势- 模型类用
InferenceClientModel，旧教程的HfApiModel已退役