smolagents 内置工具Built-in Tools完全指南从搜索、代码执行到多模态能力的一站式 Toolbox 详解【免费下载链接】smolagents smolagents: a barebones library for agents that think in code.项目地址: https://gitcode.com/gh_mirrors/smo/smolagentssmolagents 是一个主打让 Agent 用代码思考的轻量级 Agent 框架其核心哲学之一就是把 Agent 的能力抽象为一个个接口统一、即插即用的Tool。本文以官方参考文档 default_tools.md 为骨架逐一剖析 smolagents 开箱即用的全部内置工具从网页搜索、信息检索到 Python 代码执行、人机交互、语音转写与工作流收尾并结合 default_tools.py 源码与 test_default_tools.py 测试用例讲清每个工具的配置参数、底层实现原理与真实使用姿势。读完本文你将能够熟练挑选、配置并组合这些内置工具直接搭建可运行的搜索型、计算型与多模态 Agent。内置工具总览按职能划分的六类 Toolbox根据官方参考文档smolagents 的内置工具按核心职能可分为六大类全部是Tool基类的具体实现遵循完全一致的接口约定类别工具工具名name核心能力信息检索ApiWebSearchToolweb_search基于 API 的网页搜索默认 Brave Search信息检索DuckDuckGoSearchToolweb_search基于 DuckDuckGo 引擎的网页搜索信息检索GoogleSearchToolweb_search基于 SerpAPI / SERPER 的 Google 搜索信息检索WebSearchToolweb_search多引擎网页搜索DuckDuckGo / Bing / Exa信息检索WikipediaSearchToolwikipedia_search检索维基百科词条摘要或全文网页交互VisitWebpageToolvisit_webpage访问网页并将其 HTML 转成 Markdown代码执行PythonInterpreterToolpython_interpreter在受限沙箱中执行 Python 代码用户交互UserInputTooluser_input向用户提问并收集终端输入语音处理SpeechToTextTooltranscriber将音频转写为文本Whisper工作流控制FinalAnswerToolfinal_answer收尾 Agent 工作流输出最终答案所有工具都遵循统一的Tool接口声明name、description、inputs、output_type四个类属性实现forward方法通过__call__触发。这套约定的具体细节决定了内置工具拿来即用的体验值得先看清楚。统一的接口约定内置工具背后的 Tool 基类内置工具之所以能无缝嵌入任何 Agent是因为它们都遵守 tools.py 中Tool基类定义的四项硬性约束tools.pydescriptionstr对工具功能、输入与输出的简短描述会被注入 Agent 的 system prompt帮助模型决定何时调用namestr工具的唯一标识必须是合法的 Python 标识符且不能是保留字inputsdict每个输入参数的 JSON Schema 描述包含type与description两个必备键type必须是授权类型string、boolean、integer、number、image、audio、array、object、any、null之一output_typestr工具输出的数据类型同样是上述授权类型之一。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_searchWikipediaSearchTool除外因此同一时刻通常只挂载一个搜索工具避免 Agent 混淆。DuckDuckGoSearchTool零配置的免费网页搜索DuckDuckGoSearchTool是上手门槛最低的搜索工具不要求任何 API Key。其定义与默认参数如下default_tools.pyfrom smolagents import DuckDuckGoSearchTool tool DuckDuckGoSearchTool(max_results5, rate_limit2.0) results tool(Hugging Face) print(results)核心参数max_resultsint默认10单次搜索返回的最大结果条数rate_limitfloat 或 None默认1.0每秒最大查询次数用于礼貌限速、规避封禁。设为None可关闭限速**kwargs透传给底层DDGS客户端例如测试用例中的timeout20见 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 能据此自我修正。GoogleSearchToolSerpAPI / SERPER 双提供商GoogleSearchTool通过第三方搜索引擎 API 实现 Google 检索需要环境变量提供 API Keydefault_tools.pyfrom smolagents import GoogleSearchTool # provider 二选一serpapi默认或 serper tool GoogleSearchTool(providerserpapi) results tool(smolagents, filter_year2024)providerstr默认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 APIdefault_tools.pyfrom smolagents import ApiWebSearchTool tool ApiWebSearchTool(rate_limit50.0) # Brave 免费额度下可适当提高 QPS results tool(Hugging Face)构造函数支持以下参数endpointstrAPI 端点 URL默认 Brave Search 的 Web 搜索端点api_keystr直接传入 API Key优先于环境变量api_key_namestr存放 API Key 的环境变量名默认BRAVE_API_KEYheadersdict请求头默认{X-Subscription-Token: api_key}paramsdict请求参数默认{count: 10}即每次返回 10 条结果rate_limitfloat 或 None默认1.0每秒最大请求数None关闭限速。工具内置了与DuckDuckGoSearchTool相同的限速机制以遵守 API 使用策略并把响应解析extract_results取web.results下的title/url/description与 Markdown 格式化format_markdown拆成独立方法便于子类覆写。无结果时返回No results found.字符串而非抛异常。WebSearchTool一工具三引擎DuckDuckGo / Bing / ExaWebSearchTool是覆盖面最广的搜索工具通过engine参数切换三种后端default_tools.pyfrom smolagents import WebSearchTool # 默认引擎 tool WebSearchTool(max_results10, engineduckduckgo) # 或 tool WebSearchTool(enginebing) # 或需要 EXA_API_KEY 环境变量 tool WebSearchTool(engineexa)max_resultsint默认10返回结果上限enginestr默认duckduckgoduckduckgo、bing或exa之一。三个引擎的实现方式差异很大从源码可看到三条截然不同的技术路线duckduckgo请求 DuckDuckGo 的 Lite 版本页面再用标准库html.parser写一个轻量HTMLParser子类解析搜索结果表格default_tools.pybing请求 Bing 的 RSS 输出formatrss用xml.etree.ElementTree解析item节点exa调用 Exa 的搜索 API需要在环境变量中配置EXA_API_KEY并会附带x-exa-integration: smolagents请求头标识集成来源测试用例专门覆盖了缺少 API Key 抛错与正常返回结果两条路径test_default_tools.py。传入不支持的引擎名会抛出ValueError(fUnsupported engine: {self.engine})。输出统一为## Search Results打头的 Markdown 列表。WikipediaSearchTool词条摘要或全文检索WikipediaSearchTool用于在维基百科中按主题检索返回词条标题、内容摘要或全文以及页面 URLdefault_tools.py。它要求必须提供user_agent这是维基媒体基金会用户代理政策的硬性要求from smolagents import CodeAgent, WikipediaSearchTool agent CodeAgent( tools[ WikipediaSearchTool( user_agentMyResearchBot (myemailexample.com), languageen, content_typesummary, # 或 text 获取全文 extract_formatWIKI, # 或 HTML ) ], model..., ) agent.run(Python_(programming_language))参数说明user_agentstr用于标识项目的 User-Agent 字符串必填传入空串会抛ValueError。默认值是一个占位邮箱生产环境务必替换为真实项目信息languagestr默认en检索的语言版本content_typesummary或text默认text返回词条摘要还是全文extract_formatWIKI或HTML默认WIKI输出内容的提取格式内部映射到wikipediaapi.ExtractFormat枚举非法值会抛ValueError。使用前提pip install wikipedia-api。词条不存在时返回提示信息而非抛错便于 Agent 换词重试输出格式为带标题与Read more链接的文本。网页交互VisitWebpageTool 把网页读成 MarkdownVisitWebpageTool负责打开网页并读取正文与搜索工具天然互补搜索拿到链接访问工具拿到内容。其实现思路是使用requests抓取 HTML再用markdownify转成 Markdown 文本default_tools.pyfrom smolagents import VisitWebpageTool tool VisitWebpageTool(max_output_length40000) content tool(https://example.com/article)max_output_lengthint默认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 沙箱内运行 PythonPythonInterpreterTool是 smolagentsAgent 用代码思考理念的直接体现它把一个 Python 代码片段放进受限执行器里运行并返回输出default_tools.pyfrom smolagents import PythonInterpreterTool tool PythonInterpreterTool(authorized_imports[numpy], timeout_seconds30) result tool(import numpy as np\nprint(np.arange(5).sum())\nresult 42) print(result) # Stdout: # 10 # Output: 42关键参数authorized_importslist可选允许导入的额外第三方库白名单。工具默认的BASE_BUILTIN_MODULES来自 utils.py包含collections、datetime、itertools、math、queue、random、re、stat、statistics、time、unicodedata等标准库模块。传入的列表会与这份默认清单做并集set(BASE_BUILTIN_MODULES) | set(authorized_imports)timeout_secondsint 或 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_failtest_default_tools.py还验证了试图导入白名单之外的模块会直接失败这正体现了沙箱的隔离价值。用户交互UserInputTool 实现 Human-in-the-LoopUserInputTool让 Agent 可以在执行过程中停下来向用户提问实现人机协作default_tools.pyfrom 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.pyfrom smolagents import SpeechToTextTool tool SpeechToTextTool() text tool(/path/to/audio.mp3) # 支持本地路径、URL 或张量实现要点均可从源码确认默认模型openai/whisper-large-v3-turbodefault_checkpoint通过transformers加载处理器与模型分别使用WhisperProcessor和WhisperForConditionalGeneration在__new__中动态绑定输入类型audio来自agent_types.AgentAudio支持本地路径、URL 或张量encode阶段会统一转成原始音频再预处理为模型输入特征三段式流程encode预处理→forwardmodel.generate生成 token→decodebatch_decode去特殊 token 得纯文本这正是PipelineTool的标准模式。使用前提需要安装transformers、torch、accelerate即pip install smolagents[transformers]见 tools.py模型首次使用时从 Hub 下载。测试TestSpeechToTextTooltest_default_tools.py验证了实例化时正确绑定WhisperProcessor与WhisperForConditionalGeneration。在推理成本敏感的场景也可以把SpeechToTextTool换成部署好的独立转写服务但框架内置的这个版本胜在零额外工程成本。工作流控制FinalAnswerTool 给 Agent 一个终场哨FinalAnswerTool是每个 Agent 默认携带的收尾工具default_tools.pyfrom 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()], modelInferenceClientModel(), add_base_toolsTrue, # 默认 False ) agent.run(Who is the CEO of Hugging Face?)add_base_toolsbool默认False置为True时框架会把TOOL_MAPPING中的默认工具自动加入 toolbox。TOOL_MAPPING定义于 default_tools.py包含三个以name为键的条目python_interpreterPythonInterpreterTool、web_searchDuckDuckGoSearchTool与visit_webpageVisitWebpageTool一个值得注意的例外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}建字典的后挂载的会覆盖先挂载的同名工具。快速上手一个集搜索、访问与计算于一体的完整示例把本文介绍的工具组合起来就能构建一个具备检索 → 阅读 → 计算完整链路的最小 Agentfrom smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool, VisitWebpageTool agent CodeAgent( tools[ DuckDuckGoSearchTool(max_results5, rate_limit2.0), # 免密钥搜索 VisitWebpageTool(max_output_length20000), # 阅读搜索结果页面 ], modelInferenceClientModel(), add_base_toolsTrue, # 自动补上 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.pyTool基类与校验、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考