当前位置：首页 > news >正文

smolagents学习笔记系列（五）Tools-in-depth-guide

news 来源：原创 2025/9/14 22:38:18

这篇文章锁定官网教程中的 Tools-in-depth-guide 章节，主要介绍了如何详细构造自己的Tools，在之前的博文 smolagents学习笔记系列（二）Agents - Guided tour 中我初步介绍了下如何将一个函数或一个类声明成 smolagents 的工具，那么这篇文章将对这部分内容进一步深入。

官网链接：https://huggingface.co/docs/smolagents/v1.9.2/en/tutorials/tools

What is a tool, and how to build one?

Tool是Agent系统在LLM中使用最广泛的东西，根据smolagents框架的要求，想要使用tool必须对以下内容进行定义：

name：工具名，最好是能直接表述工具功能的名字；
description：功能描述，对这个工具功能的详细表述；
input types and descriptions：输入类型与描述；
output type：输出类型；

官网提供了一个将类包装成工具的示例，如果是想通过类的方式定义工具的话需要继承smolagents Tool，并且要重写 forward 这个函数，目前可以粗略地认为这个函数就是最终执行的函数。该工具的作用是找到 HuggingFace 仓库中以 downloads 为分类指定 task 功能的模型，返回最受欢迎的模型信息。

但是直接运行看不到任何结果，需要在后面加一句输出内容，这里我让这个工具对象执行了 text-classification ：

from smolagents import Toolclass HFModelDOwnloadsTool(Tool):name = "model_download_counter"description = """This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub.It returns the name of the checkpoint."""inputs = {"task": {"type": "string","description": "the task category (such as text-classification, depth-estimation, etc)",}}output_type = "string"def forward(self, task:str):from huggingface_hub import list_modelsmodel = next(iter(list_models(filter=task, sort="downloads", direction=-1)))return model.idmodel_download_tool = HFModelDOwnloadsTool()print(model_download_tool.forward("text-classification"))

运行：

$ (LLM) ~/Desktop/LLM $ python demo.py 
cross-encoder/ms-marco-MiniLM-L-6-v2

如果你在运行时报错下面的错：

huggingface_hub.errors.HfHubHTTPError: 401 Client Error: Unauthorized for url: https://huggingface.co/api/models?filter=text-classification&sort=downloads&direction=-1

需要在bash中设置环境变量：

$ export HF_TOKEN="你之前的token码"

Import a Space as a tool

smolagents提供了另一种方式允许你通过 Tool.from_space 这个函数从HuggingFace Hub中直接导入开源的工具，官网的示例用了 FLUX.1-dev 作为示例，如果你直接运行仍然是无法运行的，这个时候需要通过你的 HuggingFace 账户登录 FLUX.1-dev 的仓库：https://huggingface.co/black-forest-labs/FLUX.1-dev

【注意】：如果你没有登录账号，下图中红框是不会出现的。

登录之后会有这么一个页面，点击 Agree and access repository 按钮授权使用。
在这里插入图片描述

对示例代码进行修改以显示生成的图像，并且需要将 FLUX.1-schnell 改为 FLUX.1-dev ：

from smolagents import Tool
from PIL import Image
import numpy as np
import cv2image_generation_tool = Tool.from_space("black-forest-labs/FLUX.1-dev",name="image_generator",description="Generate an image from a prompt",api_name="/infer"
)response = image_generation_tool("A sunny beach")
print(response)image = Image.open(response)
image = np.array(image)
image = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)  # PIL 是 RGB，OpenCV 需要 BGRcv2.imshow("Generated Image", image)
cv2.waitKey(0)
cv2.destroyAllWindows()

上面代码中的 response 返回的是你 本地计算机的一个路径，比如我的是下面内容从 /private/var 开始的一长串内容。

运行：

$ python demo
Loaded as API: https://black-forest-labs-flux-1-dev.hf.space ✔
/private/var/folders/zk/vtzyjvmx7f16zrstmmd3t27w0000gn/T/gradio/9026dfa2d826f1dd7a9c5089e051f2bf775bd3e972b298c9d1801a57f2b68981/image.webp

在这里插入图片描述

【注意】：这个可能需要多运行几次，因为涉及到远程GPU资源，如果申请GPU超时了就会返回错误，但是如果你运行次数太多则会报下面的错误提示你GPU使用次数超限，需要你升级到Pro账户。

gradio_client.exceptions.AppError: The upstream Gradio app has raised an exception: You have exceeded your free GPU quota (75s requested vs. 73s left). <a style="white-space: nowrap;text-underline-offset: 2px;color: var(--body-text-color)" href="https://huggingface.co/settings/billing/subscription">Subscribe to Pro</a> to get 5x more daily usage quota.

【Tips】：如果你想直接使用这个图像生成工具，可以在浏览器中直接访问网站：https://black-forest-labs-flux-1-dev.hf.space，这个是 FLUX.1 提供的一个网页，在输入你的prompt后点击 run 即可根据你的提示词生成图像，这个过程是逐步得到的，因此刚开始你会看到一篇马赛克，稍微等待一小会儿即可得到最终结果。

在这里插入图片描述

之后官网提到了可以将这个工具作为Agent的输入，先让 Qwen2.5-Coder 对提示词进行改进，然后再调用 FLUX.1 生成图像。

from smolagents import CodeAgent, HfApiModel
from smolagents import Toolimage_generation_tool = Tool.from_space("black-forest-labs/FLUX.1-schnell",name="image_generator",description="Generate an image from a prompt"
)model = HfApiModel("Qwen/Qwen2.5-Coder-32B-Instruct")
agent = CodeAgent(tools=[image_generation_tool], model=model)response = agent.run("Improve this prompt, then generate an image of it.", additional_args={'user_prompt': 'A rabbit wearing a space suit'}
)print(response)

【注】因为我当天的GPU资源用完了，后续恢复后我会补上相应的内容。

Use LangChain tools

在使用 LangChain 这个工具之前需要安装一些依赖：

$ pip install -U langchain-community
$ pip install langchain google-search-results -q

但是很遗憾，官网的demo仍然无法直接运行，因为你需要申请一个 Serp API Key：

登录Serp官网：https://serpapi.com/users/welcome；
绑定/注册账号、在邮箱中验证、绑定中国区手机号并获得验证码；
白嫖一个免费的API；

在这里插入图片描述

在获得 Serp API Key 之后需要在环境变量中注册这个Key值：

$ export SERPAPI_API_KEY="你的Serp API Key"

对示例代码进行稍微修改，添加model对象后运行代码：

from smolagents import Tool, CodeAgent, HfApiModel
from langchain.agents import load_toolsmodel = HfApiModel()search_tool = Tool.from_langchain(load_tools(["serpapi"])[0])agent = CodeAgent(tools=[search_tool], model=model)agent.run("How many more blocks (also denoted as layers) are in BERT base encoder compared to the encoder from the architecture proposed in Attention is All You Need?")

运行结果，和之前文章中提到的一样，在默认状态下调用的是 Qwen/Qwen2.5-Coder-32B-Instruct 模型：
在这里插入图片描述

Manage your agent’s toolbox

官方提供了一个基于 HuggingFace Hub 的工具箱管理管理功能，但这个功能需要在你已经将工具上传到 Hub 的 Spaces 前提下使用，对于大多数人而言不需要将自己写的工具上传上去，因此这里就放上示例，我也没有运行测试：

from smolagents import HfApiModel
from smolagents import CodeAgent, Tool, load_toolmodel_download_tool = load_tool("{your_username}/hf-model-downloads",trust_remote_code=True
)model = HfApiModel("Qwen/Qwen2.5-Coder-32B-Instruct")agent = CodeAgent(tools=[], model=model, add_base_tools=True)
agent.tools[model_download_tool.name] = model_download_tool

如果你对大家开源的 Tools 感兴趣，可以进入 Spaces 网页： https://huggingface.co/spaces 去查看有哪些可用的工具，网页向下拉就可以看到上面我们使用的 FLUX.1-dev 这个工具，不同的工具有不同的授权和使用方式，需要自己去阅读感兴趣的工具如何使用。
在这里插入图片描述

官方demo中其实还介绍了使用 slug 和 mcp 的方式调用工具，但这两种方式我没有用过，如果后续需要的话我会进行补充。

What is a tool, and how to build one?

Import a Space as a tool

Use LangChain tools

Manage your agent’s toolbox

相关文章：