这篇文章锁定官网教程中的 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 Tool
class 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_models
model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
return model.id
model_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 cv2
image_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 需要 BGR
cv2.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 Tool
image_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_tools
model = 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_tool
model_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 的方式调用工具，但这两种方式我没有用过，如果后续需要的话我会进行补充。
