smolagents：让AI智能体用代码思考，提升任务执行效率与灵活性

在AI智能体开发领域，如何让大语言模型更高效、灵活地执行复杂任务是一个核心挑战。传统方法通常依赖预定义的工具调用指令（如JSON格式），这限制了智能体的表达能力和动态规划空间。smolagents库创新性地采用了“代码即动作”范式，允许模型将行动规划直接生成为可执行的Python代码片段。这种设计不仅减少了约30%的推理步骤，还赋予了智能体使用条件判断、循环等编程逻辑的能力，从而能更自然地处理多步

weixin_33696106

410人浏览 · 2026-04-24 09:39:31

weixin_33696106 · 2026-04-24 09:39:31 发布

1. 项目概述：当智能体开始“写代码”思考

如果你最近在关注AI智能体领域，可能会发现一个有趣的现象：很多框架都在试图让大语言模型（LLM）学会“调用工具”，比如让模型输出一个JSON，告诉系统“现在我要用搜索工具，关键词是XXX”。这种方式固然有效，但总让人觉得模型像个蹩脚的指挥官，需要把复杂的意图拆解成一个个僵硬的指令。有没有可能，我们让智能体直接用更自然、更强大的方式来表达它的“行动”呢？这就是Hugging Face新推出的 smolagents 库试图回答的问题。

smolagents 的核心哲学是 “让智能体用代码思考” 。它不是一个臃肿的全功能平台，而是一个极其精简（“smol”即“small”的趣称）的库，其核心代理逻辑仅用大约1000行代码实现。它的王牌功能 CodeAgent 允许大语言模型将每一步行动规划直接写成可执行的Python代码片段。想象一下，你问智能体：“比较一下东京、京都和大阪未来一周的天气，并推荐一个最适合观光的城市。”一个传统的工具调用智能体可能需要分三步：调用天气API获取东京数据、再调用一次获取京都数据、再调用一次获取大阪数据，最后再推理。而一个 CodeAgent 可能会直接生成一段包含循环和条件判断的代码，一次性获取所有数据并进行比较，效率自然更高。

这种设计并非空穴来风，背后有研究支撑：让模型输出代码动作，相比传统的工具调用JSON格式，能减少约30%的推理步骤，并且在复杂任务基准测试上达到更高的成功率。对于开发者而言，这意味着更低的API调用成本和更强大的任务处理能力。 smolagents 的目标用户很明确：任何希望快速构建高效、灵活且易于定制的AI智能体的开发者、研究员或爱好者。无论你是想做一个自动化的数据分析助手，还是一个能操作浏览器的网络爬虫，抑或是一个多模态的内容理解工具， smolagents 都提供了一个轻量级但功能强大的起点。

2. 核心设计理念：极简抽象与代码优先

2.1 为什么选择“代码即动作”？

在深入使用之前，理解 smolagents 选择“代码即动作”（Code as Action）范式的深层原因至关重要。这不仅仅是技术选型，更是一种对智能体本质的思考。

传统的工具调用智能体（在 smolagents 中对应 ToolCallingAgent ）工作流程类似于“翻译-执行”。LLM需要将复杂的自然语言指令，翻译成一系列预定义的、结构化的工具调用指令（通常是JSON）。这个过程存在两个瓶颈：第一， 表达能力受限 。工具调用的格式是固定的，很难表达复杂的逻辑，比如“如果A条件成立，就循环执行B工具5次，否则执行C工具”。第二， 规划与执行分离 。模型需要先“想”好整个步骤序列，再一步步执行，无法在执行中间步骤后根据结果动态调整后续的“代码”逻辑（虽然可以通过多次调用实现，但效率低下）。

而 CodeAgent 将动作的“规划”和“表达”合二为一。模型直接输出Python代码，这段代码本身可以包含条件判断、循环、变量定义、函数调用（即工具使用）等所有编程语言能提供的逻辑结构。这相当于给了模型一个更强大的“行动语言”。例如，处理“获取三个城市天气并比较”的任务，模型可以写出：

cities = [“Tokyo”, “Kyoto”, “Osaka”]
weather_data = {}
for city in cities:
    weather_data[city] = get_weather(city) # get_weather 是一个已注册的工具
# 后续比较逻辑也可以直接写在代码里
best_city = max(weather_data.items(), key=lambda x: x[1][‘sunny_hours’])
final_answer(best_city[0])

这段代码作为一个完整的“动作”被执行。这不仅减少了模型需要发起“思考-输出”循环的次数（从可能的三次以上减少到一次），也让模型的推理过程更连贯、更接近人类的思维模式——我们也是先在大脑里形成一个包含分支和循环的计划，然后才去执行。

2.2 极简主义的架构哲学

smolagents 的“smol”体现在它刻意保持了最少的抽象层。很多智能体框架会引入大量复杂的概念，如“工作流”、“编排器”、“记忆存储引擎”等，虽然功能强大，但学习曲线陡峭，且黑盒化严重。 smolagents 反其道而行之，它的核心抽象只有几个： Agent （智能体）、 Model （模型）、 Tool （工具）、 Memory （记忆）和 Executor （执行器）。

这种极简设计带来了几个显著优势：

易于理解与调试 ：由于逻辑集中（主要都在 agents.py 中），你可以很容易地阅读源码，理解智能体每一步在做什么。当出现问题时，追踪bug的路径非常短。
高度可定制 ：没有沉重的框架束缚，你可以像搭积木一样替换其中的任何部分。例如，你可以轻松实现一个自定义的 Memory 类来采用向量数据库进行长上下文记忆，或者实现一个特殊的 Tool 来连接内部企业系统。
避免抽象泄漏 ：复杂的框架有时为了通用性，会隐藏关键细节，导致你在需要微调时无从下手。 smolagents 几乎将所有控制权都暴露给开发者，你清楚地知道模型输入了什么、输出了什么、代码如何被解析和执行。

这种设计理念暗示着， smolagents 更适合那些不满足于“开箱即用但不可控”，而是希望“深度掌控并灵活构建”的开发者。它提供的是坚固的基石和清晰的接口，而不是一个封装好的黑箱应用。

3. 快速上手指南：从安装到第一个智能体

3.1 环境搭建与基础安装

开始使用 smolagents 的第一步是安装。官方推荐使用 pip 安装带有默认工具集的版本，这些工具能让你快速体验智能体的能力。

pip install “smolagents[toolkit]”

这个 [toolkit] 额外依赖项会安装一些常用的工具，比如 WebSearchTool （网络搜索）、 PythonREPLTool （Python交互式环境）等。如果你只需要最核心的库，可以只安装 pip install smolagents ，然后在需要时单独安装或自定义工具。

安装完成后，我强烈建议先在一个干净的Python环境（如 venv 或 conda ）中进行，以避免依赖冲突。接下来，让我们用不到10行代码创建一个能进行网络搜索的智能体。

3.2 创建你的第一个CodeAgent

下面的例子展示了 smolagents 最基本的用法：创建一个模型、准备工具、实例化智能体并运行。

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

# 1. 选择模型：这里使用Hugging Face Inference API的默认模型
model = InferenceClientModel()
# 2. 准备工具：给智能体装备网络搜索能力
tools = [WebSearchTool()]
# 3. 创建智能体：指定模型、工具，并开启流式输出以便观察思考过程
agent = CodeAgent(tools=tools, model=model, stream_outputs=True)

# 4. 运行任务！
response = agent.run(“How many seconds would it take for a leopard at full speed to run through Pont des Arts?”)
print(response)

执行这段代码，你会看到智能体开始“思考”。由于设置了 stream_outputs=True ，你将在控制台看到实时的输出流：智能体可能会先生成一段代码去搜索“猎豹最快速度”和“艺术桥长度”，然后执行这段代码，获取搜索结果，再进行计算，最后调用 final_answer 工具给出答案。整个过程是自动的、多步的。

这里有几个关键点需要注意：

InferenceClientModel ：这是一个网关模型，它默认连接到 Hugging Face 的免费推理端点。对于初步实验和原型设计非常方便，无需API密钥。但对于生产或高频使用，你可能需要配置自己的推理服务器或使用其他模型提供商。
WebSearchTool ：这是一个预置工具。它的实现可能依赖于某个搜索API（如SerperAPI、Tavily等）。在首次使用时，你可能需要设置相应的环境变量（如 SERPER_API_KEY ）。请查阅相关工具的文档。
stream_outputs=True ：这个参数对于调试和理解智能体工作流程至关重要。强烈建议在开发阶段始终开启。

3.3 模型选择：连接任意LLM

smolagents 是模型无关的，这是它的另一个强大之处。你可以轻松切换不同的模型后端。以下是一些常见配置示例：

使用本地Transformer模型（通过 transformers 库）：

from smolagents import TransformersModel
model = TransformersModel(
    model_id=“Qwen/Qwen3-Next-80B-A3B-Thinking”, # 任何Hugging Face模型ID
    max_new_tokens=4096,
    device_map=“auto” # 自动分配GPU/CPU
)

这种方式适合拥有强大GPU硬件、注重数据隐私或需要离线运行的场景。你需要确保本地有足够的显存来加载对应模型。

使用OpenAI兼容的API（如Together AI、OpenRouter）：

import os
from smolagents import OpenAIModel
model = OpenAIModel(
    model_id=“deepseek-ai/DeepSeek-R1”, # 在Together平台上的模型名
    api_base=“https://api.together.xyz/v1/”, # Together的API端点
    api_key=os.environ[“TOGETHER_API_KEY”]
)

通过 OpenAIModel 类，你可以接入任何提供OpenAI兼容接口的服务，这提供了极大的灵活性。

使用LiteLLM统一接口（接入100+模型）：

from smolagents import LiteLLMModel
model = LiteLLMModel(
    model_id=“anthropic/claude-4-sonnet-latest”,
    temperature=0.2,
    api_key=os.environ[“ANTHROPIC_API_KEY”]
)

LiteLLM是一个优秀的抽象层，它统一了众多云厂商（OpenAI, Anthropic, Google, Cohere等）的API调用方式。通过 smolagents 的集成，你可以用同一套代码轻松切换不同来源的顶级模型。

实操心得：模型选型建议 对于刚入门和快速原型设计， InferenceClientModel 或 OpenAIModel （使用GPT-4o）是最简单稳定的选择。当任务需要极强的推理或代码能力时，可以尝试 DeepSeek-R1 或 Claude 3.5 Sonnet 。如果追求成本与性能的平衡，并且任务以中文为主， Qwen 系列和 DeepSeek-Coder 是非常出色的开源选择。在切换模型时，注意调整 max_tokens 和 temperature 参数，代码生成任务通常需要更长的上下文和更低的温度（如0.1-0.3）以保证稳定性。

4. 核心组件深度解析

4.1 工具（Tools）：智能体的手脚

工具是智能体与外界交互的桥梁。 smolagents 对工具系统的设计非常开放和灵活。

内置工具与自定义工具： 库自带了一些实用工具，如 WebSearchTool , PythonREPLTool , FileReadTool , FileWriteTool 等。查看 smolagents.tools 模块可以获取完整列表。但真正的力量在于自定义。创建一个工具非常简单，你只需要定义一个继承自 Tool 的类，并实现 __call__ 方法。

from smolagents import Tool
import requests

class GetWeatherTool(Tool):
    name = “get_weather”
    description = “Fetches the current weather for a given city.”
    inputs = {“city”: {“type”: “string”, “description”: “The name of the city.”}}
    output_type = “string”

    def __call__(self, city: str):
        # 这里调用一个真实的天气API，例如 OpenWeatherMap
        api_key = os.getenv(“OWM_API_KEY”)
        url = f“http://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}&units=metric”
        response = requests.get(url)
        data = response.json()
        if response.status_code == 200:
            temp = data[‘main’][‘temp’]
            desc = data[‘weather’][0][‘description’]
            return f“The current weather in {city} is {desc} with a temperature of {temp}°C.”
        else:
            return f“Failed to fetch weather for {city}: {data.get(‘message’, ‘Unknown error’)}”

# 使用自定义工具
agent = CodeAgent(tools=[GetWeatherTool()], model=model)

name 和 description 至关重要，因为它们是模型理解工具功能的唯一信息来源。 description 应该清晰、具体，说明工具的作用、输入格式和输出示例。

从外部生态系统导入工具： smolagents 的强大之处在于它能无缝集成其他生态系统的工具。

从Hugging Face Space导入 ：你可以将任何一个部署在Hugging Face Space上的应用当作工具。这相当于拥有了一个海量的、即插即用的工具库。
```
from smolagents import Tool
space_tool = Tool.from_space(“username/space_name”)
```

从LangChain导入 ：如果你已经有一个基于LangChain构建的工具链，可以轻松迁移。

from langchain.tools import DuckDuckGoSearchRun
from smolagents import Tool
langchain_tool = Tool.from_langchain(DuckDuckGoSearchRun())

从MCP（Model Context Protocol）服务器导入 ：MCP是一种新兴的工具通信协议。 smolagents 支持从MCP服务器动态加载工具集。
```
from smolagents import ToolCollection
tools = ToolCollection.from_mcp(server_uri=“your_mcp_server_uri”)
```

注意事项：工具描述的质量 工具的描述 ( description ) 直接决定了LLM能否正确使用它。避免使用模糊的语言。一个好的描述应该像一份简明的API文档： 功能 + 输入参数详解 + 输出示例 。例如，不要只写“处理文件”，而应该写“读取指定路径的文本文件内容并返回。输入： {‘filepath’: ‘string’} ，示例输出： ‘文件内容…’ ”。花时间优化工具描述，能显著提升智能体的任务成功率。

4.2 记忆（Memory）与执行流程

智能体不是一问一答的聊天机器人，它需要有记忆来维持对话上下文和任务状态。 smolagents 采用了一种简单而有效的记忆机制：将整个对话历史（包括用户消息、模型生成的代码、代码执行的结果）作为一个消息列表保存在 agent.memory 中。每次模型生成时，这个完整的记忆列表都会作为上下文喂给模型。

这种设计使得智能体具有了“反思”能力。例如，如果一段代码执行出错了，错误信息会被存入记忆。在下一轮生成中，模型能看到这个错误，并尝试生成修正后的代码。这模拟了人类调试代码的过程。

ReAct循环详解： CodeAgent 的核心是一个ReAct（Reasoning and Acting）循环，但其“行动”是代码。

观察（Observation） ：智能体观察当前状态，即它的记忆（ agent.memory ），其中包含了任务描述、之前生成的代码、代码执行的结果（包括打印输出和返回值）。
思考与规划（Reasoning/Planning） ：模型基于完整的记忆，生成下一步的“行动计划”。这个计划不是文本描述，而是一段Python代码。系统提示词（System Prompt）会指导模型以特定格式（如使用 final_answer 函数来结束任务）来编写这段代码。
行动（Act） ：代码被提交给 Executor （执行器）运行。在执行环境中，所有注册给智能体的 Tool 实例都作为可调用的函数存在。代码可以自由地调用这些工具，进行数据处理和逻辑判断。
结果观察 ：代码执行的输出（包括任何打印语句和最终返回值）被捕获，并作为一条新的“助手”消息添加到记忆中。如果代码中没有调用 final_answer 工具，循环回到步骤1；如果调用了 final_answer ，循环终止，并将参数作为智能体的最终回复返回。

这个循环的代码级控制权交给了开发者。你可以通过继承 Agent 类来修改这个循环，例如添加对代码的事前安全检查，或者在每一轮之后插入一个额外的验证步骤。

4.3 代码执行与安全沙箱（Critical！）

这是 smolagents 最需要谨慎对待的部分。让LLM生成并执行任意代码，无异于在系统中打开了一个巨大的安全漏洞。 绝对不能在不受信任的环境中使用默认的 LocalPythonExecutor 来运行来自不可控模型的代码。

smolagents 提供了多种沙箱化执行方案，你应该根据你的应用场景和安全要求来选择：

执行器类型	描述	适用场景	安全等级
`LocalPythonExecutor`	在本地Python进程中执行代码，仅做有限限制（如禁用某些危险模块）。	仅用于完全可信的开发/测试环境，例如你只运行自己精心设计提示词生成的代码。	低。非安全边界。
DockerExecutor	在独立的Docker容器中执行代码，任务完成后容器被销毁。	自托管环境，对控制度和隔离性有要求。需要本地安装Docker。	高
E2BExecutor	在E2B提供的安全、临时的云沙箱中执行代码。	生产环境或不想管理Docker的团队。E2B提供了强隔离和资源限制。	高
BlaxelExecutor	在Blaxel提供的沙箱中执行。	同E2B，是另一个优秀的托管沙箱选择。	高
ModalExecutor	在Modal的无服务器平台上执行。	需要与Modal生态集成，或希望代码执行具备高可扩展性。	高
PyodideExecutor	在浏览器或边缘环境中，通过WebAssembly沙箱执行Python代码。	前端应用、浏览器扩展或边缘计算场景。	中高

配置沙箱示例（以Docker为例）：

from smolagents import CodeAgent, DockerExecutor

# 创建一个使用Docker沙箱的执行器
executor = DockerExecutor(
    image_name=“python:3.11-slim”, # 基础镜像
    timeout=30, # 代码执行超时时间（秒）
    memory_limit=“512m”, # 内存限制
)

agent = CodeAgent(
    tools=[...],
    model=model,
    executor=executor, # 传入自定义的执行器
    stream_outputs=True
)

安全警告与最佳实践

生产环境必用沙箱 ：任何面向用户或处理不可控输入的生产服务，必须使用 DockerExecutor 、 E2BExecutor 等真正的隔离沙箱。 LocalPythonExecutor 的所谓“限制”很容易被有意的恶意代码绕过。

最小权限原则 ：即使在沙箱内，也要限制工具的能力。例如，一个只需要进行网络搜索的智能体，就不应该拥有文件写入或执行系统命令的工具。

输入过滤与验证 ：对用户输入进行清洗，防止提示词注入攻击。例如，避免直接将未经处理的用户输入拼接到给模型的系统提示词中。

资源限制 ：在沙箱配置中设置严格的超时、内存和CPU限制，防止拒绝服务攻击（DoS）。

审计与日志 ：详细记录所有生成的代码和执行结果，便于事后审计和问题排查。

5. 高级用法与实战技巧

5.1 多智能体协作与分层结构

复杂的任务往往需要分工合作。 smolagents 支持创建多智能体系统，其中一个“管理者”智能体可以将子任务分配给“工作者”智能体。这通过 MultiAgent 和 ManagerAgent 等类来实现。

一个典型的设计模式是：一个 ManagerAgent 负责解析用户的复杂请求，将其分解为多个子任务，然后为每个子任务创建或调用一个专门的 CodeAgent 去执行。管理者收集各子任务的结果，进行综合，再给出最终答案。

from smolagents import ManagerAgent, CodeAgent, Tool

# 定义两个不同专长的子智能体
research_agent = CodeAgent(tools=[WebSearchTool()], model=model, name=“研究员”)
calc_agent = CodeAgent(tools=[PythonREPLTool()], model=model, name=“计算员”) # PythonREPLTool 提供计算能力

# 创建一个管理者，它知道如何调度这两个子智能体
manager = ManagerAgent(
    agents=[research_agent, calc_agent],
    model=model,
    description=“你可以将任务分配给‘研究员’进行信息检索，或分配给‘计算员’进行数学运算。”
)

result = manager.run(“先研究一下量子计算对密码学的影响，然后估算一下RSA-2048被量子计算机破解大概还需要多少年。”)

在这个例子中，管理者可能会先让“研究员”去搜索量子计算和密码学的相关资料，获取信息后，再让“计算员”基于某些公式或数据进行估算。这种架构非常适合需要多步骤、多领域知识的复杂问题求解。

5.2 处理多模态输入

smolagents 是模态无关的。这意味着你的智能体不仅可以处理文本，还可以处理图像、视频甚至音频。关键在于使用支持多模态的LLM（如GPT-4V, Claude-3.5 Sonnet, Qwen-VL等）和提供相应的多模态工具。

例如，你可以创建一个能“看懂”图片并描述其内容的智能体：

from smolagents import CodeAgent, TransformersModel, Tool
from PIL import Image
import requests
from io import BytesIO

class ImageAnalysisTool(Tool):
    name = “analyze_image”
    description = “Downloads an image from a URL and returns a textual description of its content.”
    inputs = {“image_url”: {“type”: “string”, “description”: “The URL of the image to analyze.”}}
    output_type = “string”

    def __call__(self, image_url: str):
        # 下载图片
        response = requests.get(image_url)
        img = Image.open(BytesIO(response.content))
        # 这里需要调用一个多模态模型来生成描述
        # 作为示例，我们假设有一个本地多模态模型
        # 实际应用中，你可能需要调用API或使用 `TransformersModel` 加载多模态模型
        description = my_multimodal_model_describe(img) # 伪代码
        return description

# 使用一个支持视觉的模型，例如 Qwen-VL
vision_model = TransformersModel(model_id=“Qwen/Qwen2-VL-7B-Instruct”, device_map=“auto”)
agent = CodeAgent(tools=[ImageAnalysisTool()], model=vision_model)
# 任务可以是：“分析这张图片 https://example.com/chart.png 中的趋势。”

要实现完整的流程，你需要将图片数据以模型能理解的格式（如base64编码）放入提示词中。 smolagents 的模型类（如 OpenAIModel ）通常支持传递 messages 列表，其中可以包含图像内容。你需要根据具体模型的文档来构造多模态消息。

5.3 使用CLI快速启动与交互

除了Python API， smolagents 还提供了便捷的命令行工具，非常适合快速测试和演示。

通用智能体 ( smolagent )：

# 一次性任务
smolagent “为我的Python项目写一个README文件，项目是关于数据可视化的。” \
  --model-type “OpenAIModel” \
  --model-id “gpt-4o” \
  --tools “python_repl” \
  --imports “matplotlib pandas”

# 交互式模式（不提供任务时启动）
smolagent

交互式模式会引导你逐步选择智能体类型、工具、配置模型，最后输入任务，非常适合探索。

网页浏览智能体 ( webagent )： 这是一个专门的、具备视觉能力的网页浏览智能体，它使用 helium 库来控制浏览器。

webagent “打开豆瓣电影Top250页面，爬取第一页所有电影的标题和评分，保存到CSV文件。” \
  --model-type “LiteLLMModel” \
  --model-id “claude-3-5-sonnet-latest”

这个智能体能够“看到”网页截图，并根据视觉信息决定点击哪里、输入什么。这对于自动化一些需要图形界面交互的网页任务非常有用。

6. 性能调优与常见问题排查

6.1 提示词工程与系统提示词

CodeAgent 的行为很大程度上受其系统提示词（System Prompt）控制。虽然库内置了默认提示词，但在特定场景下，微调提示词能极大提升表现。你可以通过 system_prompt 参数来自定义。

custom_system_prompt = “””
你是一个专业的Python数据分析助手。你的任务是编写简洁、高效的Python代码来解决用户的问题。
你可以使用以下工具：
- `web_search(query)`: 搜索网络信息。
- `python_repl(code)`: 执行一段Python代码并返回结果。
请严格按照以下格式思考：
1. 理解问题。
2. 编写一段完整的Python代码来解决问题，代码中应调用合适的工具。
3. 使用 `final_answer(result)` 函数来输出最终答案。
确保代码安全、无错误。如果遇到错误，尝试在代码中修复它。
“””
agent = CodeAgent(tools=tools, model=model, system_prompt=custom_system_prompt)

提示词优化技巧：

明确角色和格式 ：像上面一样，清晰定义智能体的角色和输出格式。
提供示例 ：在提示词中加入一两个完整的思考过程示例（Few-shot Learning），能显著提高代码生成质量。
约束行为 ：强调“只使用提供的工具”、“代码必须简洁”、“必须处理可能的异常”等，可以引导模型生成更可控的代码。
迭代测试 ：针对你的常见任务类型，设计不同的测试用例，观察模型失败的原因，并据此调整提示词。

6.2 模型参数调优

不同的模型和任务需要不同的生成参数。

temperature ：控制随机性。对于代码生成任务，通常设置较低的值（0.1-0.3），以保证输出的确定性和正确性。对于需要创意的任务（如生成故事），可以调高。
max_tokens / max_new_tokens ：设置生成代码的最大长度。复杂的任务需要更长的上下文。如果模型经常在代码完成前被截断，就需要调大这个值。
top_p (nucleus sampling) ：与temperature类似，影响多样性。通常设置一个较高的值（如0.9-0.95）并与低temperature配合使用。
stop_sequences ：设置停止词。可以告诉模型在生成完代码块后停止（例如，设置 stop=[“\n\n”, “```”] ），防止它生成多余的文本。

6.3 常见问题与解决方案速查表

在实际使用中，你可能会遇到以下典型问题：

问题现象	可能原因	解决方案
智能体陷入循环，不断生成相似代码。	1. 记忆过长导致模型困惑。 2. 代码执行结果未提供有效信息，模型无法推进。	1. 尝试使用 `max_steps` 参数限制循环次数。 2. 优化工具返回的信息，使其更结构化、更具信息量。 3. 在系统提示词中强调“如果三步内未解决，应总结当前所知并请求澄清”。
生成的代码格式错误，无法被解析。	1. 模型未遵循指定的代码块格式（如三个反引号）。 2. 模型在代码前后添加了多余的解释文本。	1. 在系统提示词中严格规定输出格式，例如“将代码包裹在 ```python 和 ``` 之间”。 2. 使用 `CodeAgent` 内置的解析器，它相对鲁棒，可以尝试从输出中提取代码块。
代码执行时报错（如工具不存在、语法错误）。	1. 模型“幻觉”出了未注册的工具名。 2. 模型生成的代码有语法错误。	1. 确保工具描述清晰，并在提示词中列出所有可用工具名。 2. 执行器会将错误信息返回给记忆，模型在下一轮可能会自行修正。如果错误持续，检查提示词是否要求模型“编写可运行的代码”。
智能体忽略某些工具。	1. 工具描述不够清晰或相关。 2. 模型偏好使用它更“熟悉”的工具（如总想用Python REPL计算，而不是专用计算工具）。	1. 重写工具描述，使其功能和使用方法一目了然。 2. 在系统提示词中明确指导：“优先使用 `calculate` 工具进行数学计算，而不是在代码中硬编。”
处理复杂任务时性能低下。	1. 模型能力不足。 2. 任务过于复杂，单次生成代码难以解决。	1. 升级到更强大的模型（如GPT-4o, Claude-3.5-Sonnet, DeepSeek-R1）。 2. 使用 `ManagerAgent` 将任务分解，或引导用户将复杂问题分步提出。
沙箱执行速度慢。	1. Docker容器启动有开销。 2. 网络延迟（如E2B）。	1. 对于频繁执行的轻量任务，考虑使用 `PyodideExecutor` （如果环境允许）或复用容器（注意安全）。 2. 选择地理位置上靠近你的沙箱服务提供商。

6.4 调试技巧

开启 stream_outputs=True 和 verbose=True ：这是最基本的调试手段，可以实时看到模型的“思考”过程和代码执行日志。
检查 agent.memory ：运行结束后，打印 agent.memory 。这是一个消息列表，完整记录了整个对话历史，是分析智能体决策过程的最佳资料。
模拟执行 ：在将智能体部署到沙箱前，可以在高度可控的测试环境中（甚至是用固定的代码片段）运行，确保工具链和逻辑正确。
单元测试你的工具 ：为每个自定义工具编写单元测试，确保它们在不同输入下行为符合预期。一个不可靠的工具会导致整个智能体失败。

smolagents 以其极简的设计和强大的“代码即动作”范式，为构建下一代AI智能体提供了一个锋利而灵活的工具。它要求开发者对安全有更高的意识，但也回报以更高的效率和控制力。从简单的自动化脚本到复杂的多智能体系统，它的潜力取决于你如何组合这些简单的模块。开始实验吧，最好的学习方式就是动手创建一个能帮你解决实际问题的智能体。