smolagents 入门：用代码行动的智能体

这篇适合谁，读完能做到什么

如果你想让大模型自己搜索网页、调用工具，并分几步完成一项任务，又不想从零写调度代码，可以试试 smolagents。读完这篇，你应该能装好它，跑通一个会联网搜索的智能体，给它加一个自定义工具，并弄清代码执行有哪些限制。

smolagents 是什么，和同类有什么不同

smolagents 是 Hugging Face 推出的轻量级 Python 库，用来构建 AI 智能体^[1]。同一类的开源框架还有 LlamaIndex 和 LangGraph^[1]，选哪一个要看项目的实际需要。

smolagents 的主力智能体类型是 CodeAgent。它不要求模型输出 JSON，而是让模型生成 Python 代码来执行动作^[2]。库里还有 ToolCallingAgents，这一类依赖 JSON 或文本块，由系统解析后才执行动作^[1]。两者的区别在于动作以什么形式表达。

用代码表达动作有几个实际好处：动作可以组合和复用，图片这类复杂对象可以直接处理，理论上能表达任何计算机可以完成的任务。高质量代码本身也大量出现在大模型的训练数据里^[2]。框架本身约 1000 行代码^[2]，源码不长，适合读一读。

CodeAgent 的每一步都是一个循环。系统提示词和用户的任务先被记入日志；随后智能体把日志转成聊天消息，发给模型，从模型的回复中取出代码并执行，再把结果记入内存^[2]。理解这个循环有助于调试：如果代码执行出错，可以从日志里找到是哪一步生成了这段代码^[2]。它的 run() 方法遵循 ReAct 框架，也就是推理、行动、观察结果交替进行^[2]。

准备

你需要一个可用的 Python 环境。用下面的命令安装，其中 -U 会把已安装的版本升级到最新^[2]。若项目对版本敏感，升级前最好先记下当前版本。

pip install smolagents -U

默认的模型连接方式是 InferenceClientModel，它通过 Hugging Face 的 Serverless Inference API 访问模型。默认模型是 Qwen/Qwen2.5-Coder-32B-Instruct，你也可以在 Hub 上选择任何兼容的模型^[2]。使用 Serverless Inference API 前，需要先登录 Hub^[2]：

from huggingface_hub import login

login()

登录的目的是使用 Serverless Inference API，所以这一步和 InferenceClientModel 直接相关^[2]。

第一步：运行一个带搜索的智能体

智能体需要一份工具清单和一个模型。下面的例子给智能体配了 DuckDuckGo 搜索工具，让它为派对推荐音乐^[2]：

from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel

agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=InferenceClientModel())

agent.run("Search for the best music recommendations for a party at the Wayne's mansion.")

运行开始后，输出会显示每个工作步骤的执行轨迹，以及智能体为该步骤生成的 Python 代码^[2]。第一次运行时建议仔细看这段轨迹，它能告诉你智能体实际做了什么。如果想换模型，只需修改 InferenceClientModel 的参数，Hub 上任何兼容的模型都可以选择^[2]。示例里的任务是一段自然语言请求。把它换成你自己的问题，就能看到同一个智能体在不同任务上的表现^[2]。

第二步：添加自定义工具

@tool 装饰器可以把一个普通的 Python 函数变成智能体能调用的工具。函数的文档字符串很重要，其中的 Args 部分就是告诉模型每个参数含义的地方。下面的例子定义了一个派对菜单工具^[2]：

@tool
def suggest_menu(occasion: str) -> str:
    """
    Suggests a menu based on the occasion.
    Args:
        occasion (str): The type of occasion for the party. Allowed values are:
                        - "casual": Menu for casual party.
                        - "formal": Menu for formal party.
                        - "superhero": Menu for superhero party.
                        - "custom": Custom menu.
    """
    if occasion == "casual":
        return "Pizza, snacks, and drinks."
    elif occasion == "formal":
        return "3-course dinner with wine and dessert."
    elif occasion == "superhero":
        return "Buffet with high-energy and healthy food."
    else:
        return "Custom menu for the butler."

在文档字符串里列出允许的取值，能让智能体倾向于填写真实存在的参数值，减少它凭空编造的情况^[2]。示例的 occasion 参数只有四个允许的取值：casual、formal、superhero 和 custom，每个取值的含义都写在 Args 部分^[2]。把工具加入 tools 列表，再运行智能体即可使用：

agent = CodeAgent(tools=[suggest_menu], model=InferenceClientModel())

agent.run("Prepare a formal menu for the party.")

第三步：放行额外的导入

智能体写出的代码在受限的环境中运行。默认情况下，预先设定的安全列表之外的导入会被拦截^[2]。要允许某个模块，把它的名字以字符串的形式传给 additional_authorized_imports 参数。下面的例子放行了 datetime^[2]：

agent = CodeAgent(tools=[], model=InferenceClientModel(), additional_authorized_imports=['datetime'])

只放行任务真正需要的模块。每多放行一个模块，生成的代码能做的事情就多一些。示例中这个智能体没有任何工具（tools=[]），它只需要 datetime 这一个额外模块^[2]。

限制和常见问题

smolagents 同时支持本地语言模型和基于 API 的模型，同一套智能体代码可以适应不同的开发环境^[2]。它还提供沙箱式的代码执行，这是智能体运行自己写的代码时的主要保护^[2]。使用默认的 Serverless Inference API 时，智能体要能访问 Hugging Face 的远程服务，网络和登录状态都会影响运行^[2]。

如果任务只需要调用少量工具、不需要模型在动作之间写复杂逻辑，ToolCallingAgents 也是可以考虑的另一类智能体。选哪一类，先看任务是否适合用代码表达^[1]。ToolCallingAgents 的动作以 JSON 或文本块的形式交给系统解析，这是两类智能体最直接的区别^[1]。

如果想看清一次运行的内部过程，smolagents 采用 OpenTelemetry 标准来记录智能体运行^[2]。配合 Langfuse 和 SmolagentsInstrumentor，每次运行都可以被记录下来并逐步检查。先安装依赖^[2]：

pip install opentelemetry-sdk opentelemetry-exporter-otlp openinference-instrumentation-smolagents langfuse

然后在运行智能体之前启用插桩^[2]：

from openinference.instrumentation.smolagents import SmolagentsInstrumentor

SmolagentsInstrumentor().instrument()

分享智能体

agent.push_to_hub() 可以把整个智能体上传到 Hugging Face Hub，agent.from_hub() 再把它下载下来。示例在调用 from_hub() 时传入了 trust_remote_code=True^[2]。这个参数允许加载的智能体运行其仓库里的代码，所以只加载你信任来源的智能体。分享之后，别人可以用 from_hub() 直接下载并运行你的智能体^[2]。这意味着分享的是完整的智能体，而不只是某段提示词或代码^[2]。