工具

Smolagents 是一个实验性 API，可能随时更改。由于 API 或底层模型容易发生变化，智能体返回的结果可能有所不同。

要了解更多关于智能体和工具的信息，请务必阅读入门指南。本页面包含底层类的 API 文档。

工具基类

load_tool

smolagents.load_tool

< source >

( repo_id model_repo_id: str | None = None token: str | None = None trust_remote_code: bool = False **kwargs )

参数

repo_id (str) — 工具在 Hub 上的 Space repo ID。
model_repo_id (str, 可选) — 使用此参数可使用与所选工具的默认模型不同的模型。
token (str, 可选) — 用于在 hf.co 上识别您的令牌。如果未设置，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
trust_remote_code (bool, 可选, 默认为 False) — 需要接受此项才能从 Hub 加载工具。
kwargs (附加关键字参数，可选) — 附加关键字参数将分为两部分：与 Hub 相关的所有参数（例如 cache_dir、revision、subfolder）将用于下载工具文件，其余参数将传递给其 init。

用于从 Hub 快速加载工具的主函数。

加载工具意味着您将下载工具并在本地执行它。在运行时加载工具之前，请务必检查您下载的工具，就像您使用 pip/npm/apt 安装包时一样。

工具

smolagents.tool

< source >

( tool_function: Callable )

参数

tool_function (Callable) — 要转换为工具子类的函数。应具有每个输入和输出的类型提示。还应具有包含函数描述和“Args:”部分的文档字符串，其中描述了每个参数。

将函数转换为动态创建的工具子类的实例。

工具

class smolagents.Tool

< source >

( *args **kwargs )

智能体所用函数的基本类。继承此类并实现 forward 方法以及以下类属性

description (str) — 您的工具功能的简短描述，它期望的输入以及将返回的输出。例如，“这是一个从 url 下载文件的工具。它以 url 作为输入，并返回文件中包含的文本。”
name (str) — 将在提示智能体时用于您的工具的指示性名称。例如 "text-classifier" 或 "image_generator"。
inputs (Dict[str, Dict[str, Union[str, type, bool]]]) — 输入期望的模态字典。它有一个 type 键和一个 description 键。这用于 launch_gradio_demo 或从您的工具制作一个漂亮的 Space，也可以用于您工具生成的描述中。
output_type (type) — 工具输出的类型。这用于 launch_gradio_demo 或从您的工具制作一个漂亮的 Space，也可以用于您工具生成的描述中。

如果您的工具在可用之前有昂贵的操作要执行（例如加载模型），您还可以覆盖 setup() 方法。 setup() 将在您第一次使用工具时调用，而不是在实例化时调用。

from_dict

< source >

( tool_dict: dict[str, Any] **kwargs ) → Tool

参数

tool_dict (dict[str, Any]) — 工具的字典表示。
**kwargs — 传递给工具构造函数的附加关键字参数。

工具

工具对象。

从字典表示创建工具。

from_gradio

< source >

( gradio_tool )

从 Gradio 工具创建 Tool。

from_hub

< source >

( repo_id: str token: str | None = None trust_remote_code: bool = False **kwargs )

参数

repo_id (str) — 您要将工具推送到的存储库名称。当推送到给定组织时，它应包含您的组织名称。
token (str, 可选) — 用于在 hf.co 上识别您的令牌。如果未设置，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
trust_remote_code(str, 可选, 默认为 False) — 此标志表示您了解运行远程代码的风险，并且信任此工具。如果未将其设置为 True，则从 Hub 加载工具将失败。
kwargs (附加关键字参数，可选) — 附加关键字参数将分为两部分：与 Hub 相关的所有参数（例如 cache_dir、revision、subfolder）将用于下载工具文件，其余参数将传递给其 init。

加载 Hub 上定义的工具。

从 Hub 加载工具意味着您将下载工具并在本地执行它。在运行时加载工具之前，请务必检查您下载的工具，就像您使用 pip/npm/apt 安装包时一样。

from_langchain

< source >

( langchain_tool )

从 LangChain 工具创建 Tool。

from_space

< source >

( space_id: str name: str description: str api_name: str | None = None token: str | None = None ) → Tool

参数

space_id (str) — Hub 上的 Space ID。
name (str) — 工具的名称。
description (str) — 工具的描述。
api_name (str, 可选) — 要使用的特定 api_name，如果 space 有多个选项卡。如果未指定，将默认为第一个可用的 api。
token (str, 可选) — 添加您的令牌以访问私人空间或增加您的 GPU 配额。

工具

Space，作为一个工具。

根据其在 Hub 上的 ID 从 Space 创建 Tool。

示例

>>> image_generator = Tool.from_space(
...     space_id="black-forest-labs/FLUX.1-schnell",
...     name="image-generator",
...     description="Generate an image from a prompt"
... )
>>> image = image_generator("Generate an image of a cool surfer in Tahiti")

>>> face_swapper = Tool.from_space(
...     "tuan2308/face-swap",
...     "face_swapper",
...     "Tool that puts the face shown on the first image on the second image. You can give it paths to images.",
... )
>>> image = face_swapper('./aymeric.jpeg', './ruth.jpg')

push_to_hub

< source >

( repo_id: str commit_message: str = 'Upload tool' private: bool | None = None token: bool | str | None = None create_pr: bool = False )

参数

repo_id (str) — 您要将工具推送到的存储库名称。它应包含您在推送到给定组织时的组织名称。
commit_message (str, 可选, 默认为 "Upload tool") — 推送时提交的消息。
private (bool, 可选) — 是否将存储库设为私有。如果为 None（默认），则存储库将是公共的，除非组织的默认设置为私有。如果存储库已存在，此值将被忽略。
token (bool 或 str, 可选) — 用作远程文件 HTTP bearer 授权的令牌。如果未设置，将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
create_pr (bool, 可选, 默认为 False) — 是否创建包含已上传文件的 PR 或直接提交。

将工具上传到 Hub。

保存

< source >

( output_dir: str | Path tool_file_name: str = 'tool' make_gradio_app: bool = True )

参数

output_dir (str 或 Path) — 您要保存工具的文件夹。
tool_file_name (str, 可选) — 您要保存工具的文件名。
make_gradio_app (bool, 可选, 默认为 True) — 是否同时导出 requirements.txt 文件和 Gradio UI。

保存工具的相关代码文件，以便将其推送到 Hub。这将把工具代码复制到 output_dir 中，并自动生成

一个包含工具逻辑的 {tool_file_name}.py 文件。如果您传入 make_gradio_app=True，它还将写入
一个 app.py 文件，用于在工具导出到 Space 并使用 tool.push_to_hub() 时为工具提供 UI
一个 requirements.txt，其中包含工具使用的模块名称（在检查其代码时检测到）

设置

< source >

( )

在此处覆盖此方法以执行任何昂贵的操作，并且需要在开始使用工具之前执行。例如加载大型模型。

to_dict

< source >

( )

返回表示工具的字典

launch_gradio_demo

smolagents.launch_gradio_demo

< source >

( tool: Tool )

参数

tool (Tool) — 要启动演示的工具。

为工具启动 Gradio 演示。相应的工具类需要正确实现类属性 inputs 和 output_type。

工具集

class smolagents.ToolCollection

< source >

( tools: list[Tool] )

工具集允许在智能体的工具箱中加载工具集合。

可以从 Hub 中的集合或从 MCP 服务器加载集合，请参阅

有关示例和用法，请参阅：ToolCollection.from_hub() 和 ToolCollection.from_mcp()

from_hub

< source >

( collection_slug: str token: str | None = None trust_remote_code: bool = False ) → ToolCollection

参数

collection_slug (str) — 引用集合的集合 slug。
token (str, 可选) — 如果集合是私有的，则为身份验证令牌。
trust_remote_code (bool, 可选, 默认为 False) — 是否信任远程代码。

ToolCollection

加载了工具的工具集合实例。

从 Hub 加载工具集合。

它将集合中所有 Space 的工具集合添加到代理的工具箱中

[!NOTE] 只会获取 Space，因此您可以随意将模型和数据集添加到您的集合中，如果您希望此集合展示它们。

示例

>>> from smolagents import ToolCollection, CodeAgent

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

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

from_mcp

< 来源 >

( server_parameters: 'mcp.StdioServerParameters' | dict trust_remote_code: bool = False ) → ToolCollection

参数

server_parameters (mcp.StdioServerParameters 或 dict) — 连接到 MCP 服务器的配置参数。这可以是：
- mcp.StdioServerParameters 的实例，用于通过子进程使用标准输入/输出连接 Stdio MCP 服务器。
- 一个至少包含以下内容的 dict：
  - “url”：服务器的 URL。
  - “transport”：要使用的传输协议，可以是：
    
    “streamable-http”：可流式 HTTP 传输（默认）。
    
    “sse”：旧版 HTTP+SSE 传输（已弃用）。
trust_remote_code (bool, 可选, 默认为 False) — 是否信任执行 MCP 服务器上定义的工具代码。仅当您信任 MCP 服务器并理解在本地机器上运行远程代码的风险时，才应将此选项设置为 True。如果设置为 False，从 MCP 加载工具将失败。

ToolCollection

一个工具集合实例。

自动从 MCP 服务器加载工具集合。

此方法支持 Stdio、可流式 HTTP 和旧版 HTTP+SSE MCP 服务器。有关如何连接到每个 MCP 服务器的更多详细信息，请参阅 server_parameters 参数。

注意：将生成一个单独的线程来运行处理 MCP 服务器的 asyncio 事件循环。

Stdio MCP 服务器示例

>>> import os
>>> from smolagents import ToolCollection, CodeAgent, InferenceClientModel
>>> from mcp import StdioServerParameters

>>> model = InferenceClientModel()

>>> 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], add_base_tools=True, model=model)
>>>     agent.run("Please find a remedy for hangover.")

可流式 HTTP MCP 服务器示例

>>> 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, model=model)
>>>     agent.run("Please find a remedy for hangover.")

MCP 客户端

class smolagents.MCPClient

< 来源 >

( server_parameters: 'StdioServerParameters' | dict[str, Any] | list['StdioServerParameters' | dict[str, Any]] adapter_kwargs: dict[str, Any] | None = None )

参数

server_parameters (StdioServerParameters | dict[str, Any] | list[StdioServerParameters | dict[str, Any]]) — 连接到 MCP 服务器的配置参数。如果您想同时连接多个 MCP，则可以是一个列表。
- mcp.StdioServerParameters 的实例，用于通过子进程使用标准输入/输出连接 Stdio MCP 服务器。
- 一个至少包含以下内容的 dict：
  - “url”：服务器的 URL。
  - “transport”：要使用的传输协议，可以是：
    
    “streamable-http”：可流式 HTTP 传输（默认）。
    
    “sse”：旧版 HTTP+SSE 传输（已弃用）。
adapter_kwargs (dict[str, Any], 可选) — 要直接传递给 MCPAdapt 的其他关键字参数。

管理与 MCP 服务器的连接，并将其工具提供给 SmolAgents。

注意：只有在通过 connect() 方法启动连接后才能访问工具，该方法在初始化期间完成。如果您不使用上下文管理器，我们强烈建议使用“try … finally”来确保连接被清除。

示例

# fully managed context manager + stdio
with MCPClient(...) as tools:
    # tools are now available

# context manager + Streamable HTTP transport:
with MCPClient({"url": "https://:8000/mcp", "transport": "streamable-http"}) as tools:
    # tools are now available

# manually manage the connection via the mcp_client object:
try:
    mcp_client = MCPClient(...)
    tools = mcp_client.get_tools()

    # use your tools here.
finally:
    mcp_client.disconnect()