smolagents 内置工具（Built-in Tools）完全指南：从搜索、代码执行到多模态能力的一站式 Toolbox 详解

smolagents 内置工具（Built-in Tools）完全指南：从搜索、代码执行到多模态能力的一站式 Toolbox 详解

【免费下载链接】smolagents🤗 smolagents: a barebones library for agents that think in code.项目地址: https://gitcode.com/gh_mirrors/smo/smolagents

smolagents 是一个主打"让 Agent 用代码思考"的轻量级 Agent 框架，其核心哲学之一就是把 Agent 的能力抽象为一个个接口统一、即插即用的Tool。本文以官方参考文档 default_tools.md 为骨架，逐一剖析 smolagents 开箱即用的全部内置工具：从网页搜索、信息检索，到 Python 代码执行、人机交互、语音转写与工作流收尾，并结合 default_tools.py 源码与 test_default_tools.py 测试用例，讲清每个工具的配置参数、底层实现原理与真实使用姿势。读完本文，你将能够熟练挑选、配置并组合这些内置工具，直接搭建可运行的搜索型、计算型与多模态 Agent。

内置工具总览：按职能划分的六类 Toolbox

根据官方参考文档，smolagents 的内置工具按核心职能可分为六大类，全部是Tool基类的具体实现，遵循完全一致的接口约定：

所有工具都遵循统一的Tool接口：声明name、description、inputs、output_type四个类属性，实现forward方法，通过__call__触发。这套约定的具体细节，决定了内置工具"拿来即用"的体验，值得先看清楚。

统一的接口约定：内置工具背后的 Tool 基类

内置工具之所以能无缝嵌入任何 Agent，是因为它们都遵守 tools.py 中Tool基类定义的四项硬性约束（tools.py）：

• description（str）：对工具功能、输入与输出的简短描述，会被注入 Agent 的 system prompt，帮助模型决定何时调用；
• name（str）：工具的唯一标识，必须是合法的 Python 标识符且不能是保留字；
• inputs（dict）：每个输入参数的 JSON Schema 描述，包含type与description两个必备键，type必须是授权类型（string、boolean、integer、number、image、audio、array、object、any、null之一）；
• output_type（str）：工具输出的数据类型，同样是上述授权类型之一。

Tool在__init__之后会自动执行validate_arguments()校验（tools.py）：检查四个属性是否齐全、类型是否合法、forward方法参数是否与inputs的键完全一致。这就是为什么每个内置工具的forward(self, code)、forward(self, query)签名都精确对应其inputs字典——任何错位都会在实例化时直接抛错。

调用方式上，Tool.__call__支持把单个 dict 整体传入（只要 dict 的键与inputs匹配就会自动展开为关键字参数），并且每个工具都可以像普通函数一样直接调用，例如DuckDuckGoSearchTool()("Hugging Face")。此外还有一类专为 Transformer 模型设计的PipelineTool子类（如SpeechToTextTool），它额外约定model_class、default_checkpoint、pre_processor_class等类属性，把"预处理 → 模型前向 → 后处理"三段式流程封装进encode / forward / decode三个方法（tools.py）。

信息检索：五种网页搜索与知识检索工具

信息检索是 Agent 最常见的刚需，smolagents 一口气提供了五个检索工具，覆盖"免密钥搜索、API 搜索、多引擎搜索、百科检索"四种场景。它们的name都是web_search（WikipediaSearchTool除外），因此同一时刻通常只挂载一个搜索工具，避免 Agent 混淆。

DuckDuckGoSearchTool：零配置的免费网页搜索

DuckDuckGoSearchTool是上手门槛最低的搜索工具，不要求任何 API Key。其定义与默认参数如下（default_tools.py）：

from smolagents import DuckDuckGoSearchTool tool = DuckDuckGoSearchTool(max_results=5, rate_limit=2.0) results = tool("Hugging Face") print(results)

核心参数：

• max_results（int，默认10）：单次搜索返回的最大结果条数；
• rate_limit（float 或 None，默认1.0）：每秒最大查询次数，用于礼貌限速、规避封禁。设为None可关闭限速；
• **kwargs：透传给底层DDGS客户端（例如测试用例中的timeout=20，见 test_default_tools.py）。

使用前提：需要pip install ddgs安装底层客户端，未安装时会抛出带安装提示的ImportError。源码层面它的限速逻辑非常直白：_enforce_rate_limit()记录上次请求时间，若距上次请求不足1/rate_limit秒则time.sleep补齐（default_tools.py）。返回结果以 Markdown 链接格式组织：

## Search Results 标题 摘要正文

若查询无结果，工具会抛出Exception("No results found! Try a less restrictive/shorter query.")，引导模型换一个更宽泛的关键词重试——这是一种刻意设计的"失败反馈"，让 Agent 能据此自我修正。

GoogleSearchTool：SerpAPI / SERPER 双提供商

GoogleSearchTool通过第三方搜索引擎 API 实现 Google 检索，需要环境变量提供 API Key（default_tools.py）：

from smolagents import GoogleSearchTool # provider 二选一："serpapi"（默认）或 "serper" tool = GoogleSearchTool(provider="serpapi") results = tool("smolagents", filter_year=2024)

• provider（str，默认"serpapi"）：选择"serpapi"时读取环境变量SERPAPI_API_KEY；选择"serper"时读取SERPER_API_KEY。两者在结果解析字段（organic_resultsvsorganic）与请求端点上有所不同，源码中已分别适配；
• filter_year（可选整数）：可选输入参数，把结果限定在指定年份（内部构造cdr:1,cd_min:01/01/{year},cd_max:12/31/{year}参数）。这个参数在inputs中被标记为nullable，调用时可省略。

缺少 API Key 时构造函数会直接抛出ValueError提示你配置环境变量；按年份过滤却无结果时，异常信息会建议"放宽查询或去掉年份过滤"。每个结果条目会附带发布日期、来源与摘要片段，同样以 Markdown 格式化输出。

ApiWebSearchTool：默认 Brave Search 的 API 搜索

ApiWebSearchTool是一个可高度定制的通用 API 搜索工具，默认对接 Brave Search API（default_tools.py）：

from smolagents import ApiWebSearchTool tool = ApiWebSearchTool(rate_limit=50.0) # Brave 免费额度下可适当提高 QPS results = tool("Hugging Face")

构造函数支持以下参数：

• endpoint（str）：API 端点 URL，默认 Brave Search 的 Web 搜索端点；
• api_key（str）：直接传入 API Key（优先于环境变量）；
• api_key_name（str）：存放 API Key 的环境变量名，默认"BRAVE_API_KEY"；
• headers（dict）：请求头，默认{"X-Subscription-Token": api_key}；
• params（dict）：请求参数，默认{"count": 10}，即每次返回 10 条结果；
• rate_limit（float 或 None，默认1.0）：每秒最大请求数，None关闭限速。

工具内置了与DuckDuckGoSearchTool相同的限速机制以遵守 API 使用策略，并把响应解析（extract_results，取web.results下的title/url/description）与 Markdown 格式化（format_markdown）拆成独立方法，便于子类覆写。无结果时返回"No results found."字符串而非抛异常。

WebSearchTool：一工具三引擎（DuckDuckGo / Bing / Exa）

WebSearchTool是覆盖面最广的搜索工具，通过engine参数切换三种后端（default_tools.py）：

from smolagents import WebSearchTool # 默认引擎 tool = WebSearchTool(max_results=10, engine="duckduckgo") # 或 tool = WebSearchTool(engine="bing") # 或（需要 EXA_API_KEY 环境变量） tool = WebSearchTool(engine="exa")

• max_results（int，默认10）：返回结果上限；
• engine（str，默认"duckduckgo"）："duckduckgo"、"bing"或"exa"之一。

三个引擎的实现方式差异很大，从源码可看到三条截然不同的技术路线：

• duckduckgo：请求 DuckDuckGo 的 Lite 版本页面，再用标准库html.parser写一个轻量HTMLParser子类解析搜索结果表格（default_tools.py）；
• bing：请求 Bing 的 RSS 输出（format=rss），用xml.etree.ElementTree解析<item>节点；
• exa：调用 Exa 的搜索 API，需要在环境变量中配置EXA_API_KEY，并会附带x-exa-integration: smolagents请求头标识集成来源；测试用例专门覆盖了"缺少 API Key 抛错"与"正常返回结果"两条路径（test_default_tools.py）。

传入不支持的引擎名会抛出ValueError(f"Unsupported engine: {self.engine}")。输出统一为## Search Results打头的 Markdown 列表。

WikipediaSearchTool：词条摘要或全文检索

WikipediaSearchTool用于在维基百科中按主题检索，返回词条标题、内容摘要或全文以及页面 URL（default_tools.py）。它要求必须提供user_agent，这是维基媒体基金会用户代理政策的硬性要求：

from smolagents import CodeAgent, WikipediaSearchTool agent = CodeAgent( tools=[ WikipediaSearchTool( user_agent="MyResearchBot (myemail@example.com)", language="en", content_type="summary", # 或 "text" 获取全文 extract_format="WIKI", # 或 "HTML" ) ], model=..., ) agent.run("Python_(programming_language)")

参数说明：

• user_agent（str）：用于标识项目的 User-Agent 字符串，必填；传入空串会抛ValueError。默认值是一个占位邮箱，生产环境务必替换为真实项目信息；
• language（str，默认"en"）：检索的语言版本；
• content_type（"summary"或"text"，默认"text"）：返回词条摘要还是全文；
• extract_format（"WIKI"或"HTML"，默认"WIKI"）：输出内容的提取格式，内部映射到wikipediaapi.ExtractFormat枚举，非法值会抛ValueError。

使用前提：pip install wikipedia-api。词条不存在时返回提示信息而非抛错，便于 Agent 换词重试；输出格式为带标题与"Read more"链接的文本。

网页交互：VisitWebpageTool 把网页读成 Markdown

VisitWebpageTool负责"打开网页并读取正文"，与搜索工具天然互补：搜索拿到链接，访问工具拿到内容。其实现思路是使用requests抓取 HTML，再用markdownify转成 Markdown 文本（default_tools.py）：

from smolagents import VisitWebpageTool tool = VisitWebpageTool(max_output_length=40000) content = tool("https://example.com/article")

• max_output_length（int，默认40000）：返回内容的字符数上限。超过上限时会在截断处追加一行..._This content has been truncated to stay below {N} characters_...提示（_truncate_content方法实现），防止把过长的页面灌爆 Agent 上下文。

底层行为值得注意的几点（从源码可以确认）：

• HTTP 请求超时固定为 20 秒；超时返回 "The request timed out..."，其他网络异常返回Error fetching the webpage: ...，而不是抛出异常——这是刻意设计，让 Agent 拿到错误文本后自行判断；
• 转换后会用正则\n{3,}→\n\n压缩多余空行，保证输出的 Markdown 干净可读；
• 依赖requests与markdownify，未安装时会给出pip install markdownify requests的安装提示。

测试用例TestVisitWebpageTool（见 test_default_tools.py）会实际访问一个网页并断言返回内容包含预期文本，验证了该工具在真实网络环境下的可用性。

代码执行：PythonInterpreterTool 沙箱内运行 Python

PythonInterpreterTool是 smolagents"Agent 用代码思考"理念的直接体现：它把一个 Python 代码片段放进受限执行器里运行并返回输出（default_tools.py）：

from smolagents import PythonInterpreterTool tool = PythonInterpreterTool(authorized_imports=["numpy"], timeout_seconds=30) result = tool("import numpy as np\nprint(np.arange(5).sum())\nresult = 42") print(result) # Stdout: # 10 # Output: 42

关键参数：

• authorized_imports（list，可选）：允许导入的额外第三方库白名单。工具默认的BASE_BUILTIN_MODULES来自 utils.py，包含collections、datetime、itertools、math、queue、random、re、stat、statistics、time、unicodedata等标准库模块。传入的列表会与这份默认清单做并集（set(BASE_BUILTIN_MODULES) | set(authorized_imports)）；
• timeout_seconds（int 或 None，默认MAX_EXECUTION_TIME_SECONDS，即 30 秒）：单次执行的超时上限。设None可禁用超时（测试用例 test_default_tools.py 验证了自定义超时与禁用超时两条路径）。

从源码看，它本质上是本地 Python 执行器evaluate_python_code（定义于 local_python_executor.py）的一层薄封装：执行器提供print、isinstance、range、float、int、math全家桶等基础工具，并施加多重防护——单次执行 1000 万次操作上限（MAX_OPERATIONS）、100 万次 while 迭代上限（MAX_WHILE_ITERATIONS）、默认 5 万字符输出上限，以及禁止访问 dunder 属性的nodunder_getattr拦截。执行完成后，工具返回Stdout: ...与Output: ...拼接的字符串（default_tools.py）。

一个关键细节：执行器要求"同一代码片段中使用的所有变量必须在该片段内定义"，因为每次执行都从全新状态开始（state = {}），这既保证了多次调用之间的隔离，也提醒使用者让 Agent 输出自包含的代码块。测试用例test_unauthorized_imports_fail（test_default_tools.py）还验证了：试图导入白名单之外的模块会直接失败，这正体现了沙箱的隔离价值。

用户交互：UserInputTool 实现 Human-in-the-Loop

UserInputTool让 Agent 可以在执行过程中停下来向用户提问，实现人机协作（default_tools.py）：

from smolagents import UserInputTool tool = UserInputTool() answer = tool("Which city should I book the flight to?") # 终端出现提示，等待用户输入： # Which city should I book the flight to? => Type your answer here:

它的实现极其简洁：forward调用 Python 内置的input()打印问题并读取一行回答，输出类型为string。适用于需要用户偏好、确认或补充信息的场景，例如预订流程中的城市选择、需要人工审核的关键决策点等。注意它是同步阻塞的，适用于命令行交互环境（如 examples/ 中的终端 Agent 示例）。

语音处理：SpeechToTextTool 基于 Whisper 的音频转写

SpeechToTextTool是内置工具中唯一的多模态 PipelineTool，把音频文件转写为文本（default_tools.py）：

from smolagents import SpeechToTextTool tool = SpeechToTextTool() text = tool("/path/to/audio.mp3") # 支持本地路径、URL 或张量

实现要点（均可从源码确认）：

• 默认模型：openai/whisper-large-v3-turbo（default_checkpoint），通过transformers加载，处理器与模型分别使用WhisperProcessor和WhisperForConditionalGeneration（在__new__中动态绑定）；
• 输入类型：audio（来自agent_types.AgentAudio），支持本地路径、URL 或张量，encode阶段会统一转成原始音频再预处理为模型输入特征；
• 三段式流程：encode（预处理）→forward（model.generate生成 token）→decode（batch_decode去特殊 token 得纯文本），这正是PipelineTool的标准模式。

使用前提：需要安装transformers、torch、accelerate（即pip install 'smolagents[transformers]'，见 tools.py），模型首次使用时从 Hub 下载。测试TestSpeechToTextTool（test_default_tools.py）验证了实例化时正确绑定WhisperProcessor与WhisperForConditionalGeneration。在推理成本敏感的场景，也可以把SpeechToTextTool换成部署好的独立转写服务，但框架内置的这个版本胜在零额外工程成本。

工作流控制：FinalAnswerTool 给 Agent 一个"终场哨"

FinalAnswerTool是每个 Agent 默认携带的收尾工具（default_tools.py）：

from smolagents import FinalAnswerTool tool = FinalAnswerTool() tool("The answer is 42") # 原样返回 answer

它的inputs是{"answer": {"type": "any", ...}}，forward直接把答案原样返回。虽然实现上只是一层透传，它的职责却至关重要：在 Agent 的提示词体系中，final_answer是"结束本轮思考、向用户交付结果"的唯一出口。框架在组装 Agent 时会通过self.tools.setdefault("final_answer", FinalAnswerTool())确保它始终存在（见 agents.py），你传入的自定义工具列表中即便没有它也不会破坏工作流闭环。

在 Agent 中挂载内置工具：add_base_tools 与 TOOL_MAPPING

内置工具可以单独使用，但更常见的用法是作为CodeAgent/ToolCallingAgent的 toolbox。在 agents.py 的_setup_tools中可以看到框架的自动装配逻辑：

from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool agent = CodeAgent( tools=[DuckDuckGoSearchTool()], model=InferenceClientModel(), add_base_tools=True, # 默认 False ) agent.run("Who is the CEO of Hugging Face?")

• add_base_tools（bool，默认False）：置为True时，框架会把TOOL_MAPPING中的默认工具自动加入 toolbox。TOOL_MAPPING定义于 default_tools.py，包含三个以name为键的条目：python_interpreter（PythonInterpreterTool）、web_search（DuckDuckGoSearchTool）与visit_webpage（VisitWebpageTool）；
• 一个值得注意的例外：python_interpreter只有在 Agent 类型为ToolCallingAgent时才会被自动添加（if name != "python_interpreter" or self.__class__.__name__ == "ToolCallingAgent"）。原因很直接——CodeAgent本身就通过"写代码"来思考，自带代码执行能力，无需再挂一个同名工具；而ToolCallingAgent走的是工具调用范式，才需要显式的解释器工具。

由于四个搜索工具（DuckDuckGoSearchTool、GoogleSearchTool、ApiWebSearchTool、WebSearchTool）的name都是web_search，同一个 Agent 内切勿同时挂载多个，否则会触发 agents.py 中的重名校验（ValueError: Each tool or managed_agent should have a unique name!）。_setup_tools内部也是以{tool.name: tool}建字典的，后挂载的会覆盖先挂载的同名工具。

快速上手：一个集搜索、访问与计算于一体的完整示例

把本文介绍的工具组合起来，就能构建一个具备"检索 → 阅读 → 计算"完整链路的最小 Agent：

from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool, VisitWebpageTool agent = CodeAgent( tools=[ DuckDuckGoSearchTool(max_results=5, rate_limit=2.0), # 免密钥搜索 VisitWebpageTool(max_output_length=20000), # 阅读搜索结果页面 ], model=InferenceClientModel(), add_base_tools=True, # 自动补上 final_answer ) agent.run( "Search for the latest news about open-source AI agents, " "open the most relevant page, and summarize it in 3 bullet points." )

如果任务偏计算（如数据分析、数学推导），可以只依赖PythonInterpreterTool；如果涉及语音素材，则把SpeechToTextTool加入 tools 列表即可。每个工具的参数都已在前文给出默认值与取值范围，按需微调即可直接运行。

结语：内置工具是理解 smolagents Tool 体系的活教材

回顾本文，smolagents 的十个内置工具虽然各司其职，但都严格遵循统一的Tool接口，这正是整个框架"可组合、可替换、可扩展"的根基：

• 搜索类五选一按需挂载，从零配置的DuckDuckGoSearchTool到多引擎WebSearchTool、API 型ApiWebSearchTool/GoogleSearchTool，再到百科检索WikipediaSearchTool，覆盖免密钥与高配额两类场景；
• 网页访问VisitWebpageTool与搜索工具组成"检索-阅读"闭环，输出长度可控、异常信息可回喂给模型；
• 计算由PythonInterpreterTool沙箱承接，白名单导入 + 超时 + 操作数上限多重防护；
• 人机协作与收尾分别由UserInputTool与FinalAnswerTool承担；
• 多模态由SpeechToTextTool示范了PipelineTool的封装范式。

如果想深入每个参数的校验逻辑或自定义自己的工具，可以继续阅读 tools.py（Tool基类与校验）、tools.md（工具参考文档）以及 tools.md（自定义工具教程）；内置工具的全部实现集中在 default_tools.py，配套测试在 test_default_tools.py，是学习与二次开发的绝佳起点。

【免费下载链接】smolagents🤗 smolagents: a barebones library for agents that think in code.项目地址: https://gitcode.com/gh_mirrors/smo/smolagents