工具

在这里，我们将看到高级工具的使用方法。

如果您是构建代理的新手，请务必先阅读代理简介和smolagents 入门指南。

什么是工具，如何构建它？

工具主要是LLM在代理系统中可以使用的一个函数。

但要使用它，LLM需要被赋予一个API：名称、工具描述、输入类型和描述、输出类型。

所以它不能仅仅是一个函数。它应该是一个类。

因此，核心的工具是一个类，它用元数据封装了一个函数，这些元数据有助于LLM理解如何使用它。

它看起来像这样：

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_downloads_tool = HFModelDownloadsTool()

自定义工具继承自Tool，以继承有用的方法。子类还定义了

一个属性 `name`，对应于工具本身的名称。名称通常描述工具的功能。由于代码返回任务下载量最多的模型，我们将其命名为 `model_download_counter`。
一个 `description` 属性，用于填充代理的系统提示。
一个 `inputs` 属性，它是一个字典，包含键 `“type”` 和 `“description”`。它包含有助于 Python 解释器对输入做出明智选择的信息。
一个 `output_type` 属性，指定输出类型。`inputs` 和 `output_type` 的类型都应该是 Pydantic 格式，它们可以是以下任意一种：`~AUTHORIZED_TYPES()`。
一个 `forward` 方法，其中包含要执行的推理代码。

这就是在代理中使用它所需要的一切！

还有另一种构建工具的方法。在入门指南中，我们使用`@tool`装饰器实现了一个工具。建议使用tool()装饰器来定义简单的工具，但有时您需要更多：在一个类中使用多个方法以提高清晰度，或者使用额外的类属性。

在这种情况下，您可以通过如上所述继承 Tool 来构建您的工具。

将您的工具分享到 Hub

您可以通过在工具上调用 push_to_hub() 将自定义工具作为空间仓库分享到 Hub。请确保您已在 Hub 上为其创建了一个仓库，并且正在使用具有读取权限的令牌。

model_downloads_tool.push_to_hub("{your_username}/hf-model-downloads", token="<YOUR_HUGGINGFACEHUB_API_TOKEN>")

为了将工具成功推送到 Hub，您的工具需要遵守一些规则：

所有方法都是自包含的，例如使用来自其参数的变量。
根据上述观点，**所有导入都应直接在工具函数内定义**，否则在尝试使用您的自定义工具调用 save() 或 push_to_hub() 时会出错。
如果继承`__init__`方法，则除了`self`之外不能给出其他参数。这是因为在特定工具实例初始化期间设置的参数难以跟踪，这会阻碍它们正确地共享到hub。无论如何，创建特定类的目的是可以为任何需要硬编码的内容设置类属性（只需在`class YourTool(Tool):`行下直接设置`your_variable=(...)`）。当然，仍然可以通过将内容分配给`self.your_variable`在代码中的任何位置创建类属性。

工具推送到 Hub 后，即可对其进行可视化。这里是我推送的 `model_downloads_tool`。它具有漂亮的 Gradio 界面。

深入查看工具文件，您会发现所有工具逻辑都在 tool.py 中。您可以在那里检查他人共享的工具。

然后，您可以使用 load_tool() 加载工具或使用 from_hub() 创建工具，并将其传递给代理中的 `tools` 参数。由于运行工具意味着运行自定义代码，因此您需要确保信任该仓库，因此我们要求传递 `trust_remote_code=True` 才能从 Hub 加载工具。

from smolagents import load_tool, CodeAgent

model_download_tool = load_tool(
    "{your_username}/hf-model-downloads",
    trust_remote_code=True
)

从 MCP 服务器使用工具

我们的 `MCPClient` 允许您从 MCP 服务器加载工具，并为您提供对连接和工具管理的完全控制

对于基于 stdio 的 MCP 服务器

from smolagents import MCPClient, CodeAgent
from mcp import StdioServerParameters
import os

server_parameters = StdioServerParameters(
    command="uvx",  # Using uvx ensures dependencies are available
    args=["--quiet", "pubmedmcp@0.1.3"],
    env={"UV_PYTHON": "3.12", **os.environ},
)

with MCPClient(server_parameters) as tools:
    agent = CodeAgent(tools=tools, model=model, add_base_tools=True)
    agent.run("Please find the latest research on COVID-19 treatment.")

对于基于可流式 HTTP 的 MCP 服务器

from smolagents import MCPClient, CodeAgent

with MCPClient({"url": "http://127.0.0.1:8000/mcp", "transport": "streamable-http"}) as tools:
    agent = CodeAgent(tools=tools, model=model, add_base_tools=True)
    agent.run("Please find a remedy for hangover.")

您还可以使用try…finally模式手动管理连接生命周期

from smolagents import MCPClient, CodeAgent
from mcp import StdioServerParameters
import os

# Initialize server parameters
server_parameters = StdioServerParameters(
    command="uvx",
    args=["--quiet", "pubmedmcp@0.1.3"],
    env={"UV_PYTHON": "3.12", **os.environ},
)

# Manually manage the connection
try:
    mcp_client = MCPClient(server_parameters)
    tools = mcp_client.get_tools()

    # Use the tools with your agent
    agent = CodeAgent(tools=tools, model=model, add_base_tools=True)
    result = agent.run("What are the recent therapeutic approaches for Alzheimer's disease?")

    # Process the result as needed
    print(f"Agent response: {result}")
finally:
    # Always ensure the connection is properly closed
    mcp_client.disconnect()

您还可以通过传递服务器参数列表同时连接到多个 MCP 服务器

from smolagents import MCPClient, CodeAgent
from mcp import StdioServerParameters
import os

server_params1 = StdioServerParameters(
    command="uvx",
    args=["--quiet", "pubmedmcp@0.1.3"],
    env={"UV_PYTHON": "3.12", **os.environ},
)

server_params2 = {"url": "http://127.0.0.1:8000/sse"}

with MCPClient([server_params1, server_params2]) as tools:
    agent = CodeAgent(tools=tools, model=model, add_base_tools=True)
    agent.run("Please analyze the latest research and suggest remedies for headaches.")

安全警告：在连接到任何 MCP 服务器之前，务必验证其来源和完整性，尤其是在生产环境中。使用 MCP 服务器存在安全风险。

信任至关重要：只使用来自受信任来源的 MCP 服务器。恶意服务器可以在您的机器上执行有害代码。
基于 StdIO 的 MCP 服务器将始终在您的机器上执行代码（这是它们的预期功能）。
可流式 HTTP MCP 服务器：虽然远程 MCP 服务器不会在您的机器上执行代码，但仍需谨慎操作。

将空间导入为工具

您可以使用 Tool.from_space() 方法直接从 Hub 导入 Gradio Space 作为工具！

您只需提供 Hub 上 Space 的 ID、其名称以及一段描述，这将帮助您的代理理解该工具的功能。在底层，这将使用 `gradio-client` 库来调用 Space。

例如，我们从 Hub 导入 FLUX.1-dev 空间，并使用它来生成图像。

image_generation_tool = Tool.from_space(
    "black-forest-labs/FLUX.1-schnell",
    name="image_generator",
    description="Generate an image from a prompt"
)

image_generation_tool("A sunny beach")

瞧，这是您的图片！🏖️

然后，您可以像使用任何其他工具一样使用此工具。例如，我们来改进提示“穿着宇航服的兔子”，并生成它的图像。此示例还展示了如何将附加参数传递给代理。

from smolagents import CodeAgent, InferenceClientModel

model = InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct")
agent = CodeAgent(tools=[image_generation_tool], model=model)

agent.run(
    "Improve this prompt, then generate an image of it.", additional_args={'user_prompt': 'A rabbit wearing a space suit'}
)

=== Agent thoughts:
improved_prompt could be "A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background"

Now that I have improved the prompt, I can use the image generator tool to generate an image based on this prompt.
>>> Agent is executing the code below:
image = image_generator(prompt="A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background")
final_answer(image)

这有多酷？🤩

使用 LangChain 工具

我们热爱 Langchain，并认为它拥有一套非常引人注目的工具。要从 LangChain 导入工具，请使用 `from_langchain()` 方法。

以下是使用 LangChain 网页搜索工具重新创建介绍搜索结果的方法。此工具需要 `pip install langchain google-search-results -q` 才能正常工作。

from langchain.agents import load_tools

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?")

管理您的代理工具箱

您可以通过在属性 `agent.tools` 中添加或替换工具来管理代理的工具箱，因为它是一个标准字典。

让我们将 `model_download_tool` 添加到已使用默认工具箱初始化的现有代理中。

from smolagents import InferenceClientModel

model = InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct")

agent = CodeAgent(tools=[], model=model, add_base_tools=True)
agent.tools[model_download_tool.name] = model_download_tool

现在我们可以利用新工具了

agent.run(
    "Can you give me the name of the model that has the most downloads in the 'text-to-video' task on the Hugging Face Hub but reverse the letters?"
)

注意不要给代理添加太多工具：这可能会让较弱的LLM引擎不堪重负。

使用工具集

您可以使用 ToolCollection 来利用工具集合。它支持从 Hub 或 MCP 服务器加载工具集合。

来自任何 MCP 服务器的工具集

利用来自 glama.ai 或 smithery.ai 上数百个 MCP 服务器的工具。

MCP 服务器工具可以使用 ToolCollection.from_mcp() 加载。

安全警告：在连接到任何 MCP 服务器之前，务必验证其来源和完整性，尤其是在生产环境中。使用 MCP 服务器存在安全风险。

信任至关重要：只使用来自受信任来源的 MCP 服务器。恶意服务器可以在您的机器上执行有害代码。
基于 StdIO 的 MCP 服务器将始终在您的机器上执行代码（这是它们的预期功能）。
可流式 HTTP MCP 服务器：虽然远程 MCP 服务器不会在您的机器上执行代码，但仍需谨慎操作。

对于基于 stdio 的 MCP 服务器，将服务器参数作为 `mcp.StdioServerParameters` 的实例传递

from smolagents import ToolCollection, CodeAgent
from mcp import StdioServerParameters

server_parameters = StdioServerParameters(
    command="uvx",
    args=["--quiet", "pubmedmcp@0.1.3"],
    env={"UV_PYTHON": "3.12", **os.environ},
)

with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tool_collection:
    agent = CodeAgent(tools=[*tool_collection.tools], model=model, add_base_tools=True)
    agent.run("Please find a remedy for hangover.")

对于基于可流式 HTTP 的 MCP 服务器，只需将带有参数的字典传递给 `mcp.client.streamable_http.streamablehttp_client`，并添加键 `transport`，其值为 `"streamable-http"`

from smolagents import ToolCollection, CodeAgent

with ToolCollection.from_mcp({"url": "http://127.0.0.1:8000/mcp", "transport": "streamable-http"}, trust_remote_code=True) as tool_collection:
    agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True)
    agent.run("Please find a remedy for hangover.")

来自 Hub 中集合的工具集

您可以使用所需集合的 slug 来利用它。然后将它们作为列表传递以初始化您的代理，并开始使用它们！

from smolagents import ToolCollection, CodeAgent

image_tool_collection = ToolCollection.from_hub(
    collection_slug="huggingface-tools/diffusion-tools-6630bb19a942c2306a2cdb6f",
    token="<YOUR_HUGGINGFACEHUB_API_TOKEN>"
)
agent = CodeAgent(tools=[*image_tool_collection.tools], model=model, add_base_tools=True)

agent.run("Please draw me a picture of rivers and lakes.")

为了加快启动速度，工具仅在代理调用时加载。

< > 在 GitHub 上更新