#
Tools

> Smolagents is an experimental API which is subject to change at any time. Results returned by the agents can vary as the APIs or underlying models are prone to change.

To learn more about agents and tools make sure to read the introductory guide. This page contains the API docs for the underlying classes.

##
Tool Base Classes

###
load_tool

####
smolagents.load_tool

< source >

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

Parameters

- repo_id (`str`) — Space repo ID of a tool on the Hub.
- model_repo_id (`str`, optional) — Use this argument to use a different model than the default one for the tool you selected.
- token (`str`, optional) — The token to identify you on hf.co. If unset, will use the token generated when running `huggingface-cli login` (stored in `~/.huggingface`).
- trust_remote_code (`bool`, optional, defaults to False) — This needs to be accepted in order to load a tool from Hub.
- kwargs (additional keyword arguments, optional) — Additional keyword arguments that will be split in two: all arguments relevant to the Hub (such as `cache_dir`, `revision`, `subfolder`) will be used when downloading the files for your tool, and the others will be passed along to its init.

Main function to quickly load a tool from the Hub.

> Loading a tool means that you’ll download the tool and execute it locally. ALWAYS inspect the tool you’re downloading before loading it within your runtime, as you would do when installing a package using pip/npm/apt.

###
tool

####
smolagents.tool

< source >

( tool_function: Callable )

Parameters

- tool_function (`Callable`) — Function to convert into a Tool subclass. Should have type hints for each input and a type hint for the output. Should also have a docstring including the description of the function and an ‘Args:’ part where each argument is described.

Convert a function into an instance of a dynamically created Tool subclass.

###
Tool

###
class smolagents.Tool

< source >

( *args **kwargs )

A base class for the functions used by the agent. Subclass this and implement the `forward` method as well as the following class attributes:

- description (`str`) — A short description of what your tool does, the inputs it expects and the output(s) it will return. For instance ‘This is a tool that downloads a file from a `url`. It takes the `url` as input, and returns the text contained in the file’.
- name (`str`) — A performative name that will be used for your tool in the prompt to the agent. For instance `"text-classifier"` or `"image_generator"`.
- inputs (`Dict[str, Dict[str, Union[str, type, bool]]]`) — The dict of modalities expected for the inputs. It has one `type`key and a `description`key. This is used by `launch_gradio_demo` or to make a nice space from your tool, and also can be used in the generated description for your tool.
- output_type (`type`) — The type of the tool output. This is used by `launch_gradio_demo` or to make a nice space from your tool, and also can be used in the generated description for your tool.
- output_schema (`Dict[str, Any]`, optional) — The JSON schema defining the expected structure of the tool output. This can be included in system prompts to help agents understand the expected output format. Note: This is currently used for informational purposes only and does not perform actual output validation.

You can also override the method setup() if your tool has an expensive operation to perform before being usable (such as loading a model). setup() will be called the first time you use your tool, but not at instantiation.

####
from_dict

< source >

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

Parameters

- tool_dict (`dict[str, Any]`) — Dictionary representation of the tool.
- **kwargs — Additional keyword arguments to pass to the tool’s constructor.

Returns

`Tool`

Tool object.

Create tool from a dictionary representation.

####
from_gradio

< source >

( gradio_tool )

Creates a Tool from a gradio tool.

####
from_hub

< source >

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

Parameters

- repo_id (`str`) — The name of the Space repo on the Hub where your tool is defined.
- token (`str`, optional) — The token to identify you on hf.co. If unset, will use the token generated when running `huggingface-cli login` (stored in `~/.huggingface`).
- trust_remote_code(`str`, optional, defaults to False) — This flags marks that you understand the risk of running remote code and that you trust this tool. If not setting this to True, loading the tool from Hub will fail.
- kwargs (additional keyword arguments, optional) — Additional keyword arguments that will be split in two: all arguments relevant to the Hub (such as `cache_dir`, `revision`, `subfolder`) will be used when downloading the files for your tool, and the others will be passed along to its init.

Loads a tool defined on the Hub.

> Loading a tool from the Hub means that you’ll download the tool and execute it locally. ALWAYS inspect the tool you’re downloading before loading it within your runtime, as you would do when installing a package using pip/npm/apt.

####
from_langchain

< source >

( langchain_tool )

Creates a Tool from a langchain tool.

####
from_space

< source >

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

Parameters

- space_id (`str`) — The id of the Space on the Hub.
- name (`str`) — The name of the tool.
- description (`str`) — The description of the tool.
- api_name (`str`, optional) — The specific api_name to use, if the space has several tabs. If not precised, will default to the first available api.
- token (`str`, optional) — Add your token to access private spaces or increase your GPU quotas.

Returns

Tool

The Space, as a tool.

Creates a Tool from a Space given its id on the Hub.

Examples:

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

Parameters

- repo_id (`str`) — The name of the repository you want to push your tool to. It should contain your organization name when pushing to a given organization.
- commit_message (`str`, optional, defaults to `"Upload tool"`) — Message to commit while pushing.
- private (`bool`, optional) — Whether to make the repo private. If `None` (default), the repo will be public unless the organization’s default is private. This value is ignored if the repo already exists.
- token (`bool` or `str`, optional) — The token to use as HTTP bearer authorization for remote files. If unset, will use the token generated when running `huggingface-cli login` (stored in `~/.huggingface`).
- create_pr (`bool`, optional, defaults to `False`) — Whether to create a PR with the uploaded files or directly commit.

Upload the tool to the Hub.

####
save

< source >

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

Parameters

- output_dir (`str` or `Path`) — The folder in which you want to save your tool.
- tool_file_name (`str`, optional) — The file name in which you want to save your tool.
- make_gradio_app (`bool`, optional, defaults to True) — Whether to also export a `requirements.txt` file and Gradio UI.

Saves the relevant code files for your tool so it can be pushed to the Hub. This will copy the code of your tool in `output_dir` as well as autogenerate:

- a `{tool_file_name}.py` file containing the logic for your tool. If you pass `make_gradio_app=True`, this will also write:
- an `app.py` file providing a UI for your tool when it is exported to a Space with `tool.push_to_hub()`
- a `requirements.txt` containing the names of the modules used by your tool (as detected when inspecting its code)

####
setup

< source >

( )

Overwrite this method here for any operation that is expensive and needs to be executed before you start using your tool. Such as loading a big model.

####
to_dict

< source >

( )

Returns a dictionary representing the tool

###
launch_gradio_demo

####
smolagents.launch_gradio_demo

< source >

( tool: Tool )

Parameters

- tool (`Tool`) — The tool for which to launch the demo.

Launches a gradio demo for a tool. The corresponding tool class needs to properly implement the class attributes `inputs` and `output_type`.

##
ToolCollection

###
class smolagents.ToolCollection

< source >

( tools: list[Tool] )

Tool collections enable loading a collection of tools in the agent’s toolbox.

Collections can be loaded from a collection in the Hub or from an MCP server, see:

- ToolCollection.from_hub()
- ToolCollection.from_mcp()

For example and usage, see: ToolCollection.from_hub() and ToolCollection.from_mcp()

####
from_hub

< source >

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

Parameters

- collection_slug (str) — The collection slug referencing the collection.
- token (str, optional) — The authentication token if the collection is private.
- trust_remote_code (bool, optional, defaults to False) — Whether to trust the remote code.

Returns

ToolCollection

A tool collection instance loaded with the tools.

Loads a tool collection from the Hub.

it adds a collection of tools from all Spaces in the collection to the agent’s toolbox

> Only Spaces will be fetched, so you can feel free to add models and datasets to your collection if you’d like for this collection to showcase them.

Example:

    >>> 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

< source >

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

Parameters

- server_parameters (`mcp.StdioServerParameters` or `dict`) — Configuration parameters to connect to the MCP server. This can be:

  - An instance of `mcp.StdioServerParameters` for connecting a Stdio MCP server via standard input/output using a subprocess.

  - A `dict` with at least:

    - “url”: URL of the server.
    - “transport”: Transport protocol to use, one of:
      - “streamable-http”: Streamable HTTP transport (default).
      - “sse”: Legacy HTTP+SSE transport (deprecated).
- trust_remote_code (`bool`, optional, defaults to `False`) — Whether to trust the execution of code from tools defined on the MCP server. This option should only be set to `True` if you trust the MCP server, and undertand the risks associated with running remote code on your local machine. If set to `False`, loading tools from MCP will fail.
- structured_output (`bool`, optional, defaults to `False`) — Whether to enable structured output features for MCP tools. If True, enables:
  - Support for outputSchema in MCP tools
  - Structured content handling (structuredContent from MCP responses)
  - JSON parsing fallback for structured data If False, uses the original simple text-only behavior for backwards compatibility.

Returns

ToolCollection

A tool collection instance.

Automatically load a tool collection from an MCP server.

This method supports Stdio, Streamable HTTP, and legacy HTTP+SSE MCP servers. Look at the `server_parameters` argument for more details on how to connect to each MCP server.

Note: a separate thread will be spawned to run an asyncio event loop handling the MCP server.

Example with a Stdio MCP server:

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

Example with structured output enabled:

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

Example with a Streamable HTTP MCP server:

    >>> 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 Client

###
class smolagents.MCPClient

< source >

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

Parameters

- server_parameters (StdioServerParameters | dict[str, Any] | list[StdioServerParameters | dict[str, Any]]) — Configuration parameters to connect to the MCP server. Can be a list if you want to connect multiple MCPs at once.

  - An instance of `mcp.StdioServerParameters` for connecting a Stdio MCP server via standard input/output using a subprocess.

  - A `dict` with at least:

    - “url”: URL of the server.
    - “transport”: Transport protocol to use, one of:
      - “streamable-http”: Streamable HTTP transport (default).
      - “sse”: Legacy HTTP+SSE transport (deprecated).
- adapter_kwargs (dict[str, Any], optional) — Additional keyword arguments to be passed directly to `MCPAdapt`.
- structured_output (bool, optional, defaults to False) — Whether to enable structured output features for MCP tools. If True, enables:
  - Support for outputSchema in MCP tools
  - Structured content handling (structuredContent from MCP responses)
  - JSON parsing fallback for structured data If False, uses the original simple text-only behavior for backwards compatibility.

Manages the connection to an MCP server and make its tools available to SmolAgents.

Note: tools can only be accessed after the connection has been started with the `connect()` method, done during the init. If you don’t use the context manager we strongly encourage to use “try … finally” to ensure the connection is cleaned up.

Example:

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

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

    # Enable structured output for advanced MCP tools:
    with MCPClient(server_parameters, structured_output=True) as tools:
        # tools with structured output support 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()

####
connect

< source >

( )

Connect to the MCP server and initialize the tools.

####
disconnect

< source >

( exc_type: type[BaseException] | None = None exc_value: BaseException | None = None exc_traceback: TracebackType | None = None )

Disconnect from the MCP server

####
get_tools

< source >

( ) →
list[Tool]

Returns

list[Tool]

The SmolAgents tools available from the MCP server.

Raises

`ValueError`

- `ValueError` — If the MCP server tools is None (usually assuming the server is not started).

The SmolAgents tools available from the MCP server.

Note: for now, this always returns the tools available at the creation of the session, but it will in a future release return also new tools available from the MCP server if any at call time.

##
Agent Types

Agents can handle any type of object in-between tools; tools, being completely multimodal, can accept and return text, image, audio, video, among other types. In order to increase compatibility between tools, as well as to correctly render these returns in ipython (jupyter, colab, ipython notebooks, …), we implement wrapper classes around these types.

The wrapped objects should continue behaving as initially; a text object should still behave as a string, an image object should still behave as a `PIL.Image`.

These types have three specific purposes:

- Calling `to_raw` on the type should return the underlying object
- Calling `to_string` on the type should return the object as a string: that can be the string in case of an `AgentText` but will be the path of the serialized version of the object in other instances
- Displaying it in an ipython kernel should display the object correctly

###
AgentText

###
class smolagents.AgentText

< source >

( value )

Text type returned by the agent. Behaves as a string.

###
AgentImage

###
class smolagents.AgentImage

< source >

( value )

Image type returned by the agent. Behaves as a PIL.Image.Image.

####
save

< source >

( output_bytes format: str = None **params )

Parameters

- output_bytes (bytes) — The output bytes to save the image to.
- format (str) — The format to use for the output image. The format is the same as in PIL.Image.save.
- **params — Additional parameters to pass to PIL.Image.save.

Saves the image to a file.

####
to_raw

< source >

( )

Returns the “raw” version of that object. In the case of an AgentImage, it is a PIL.Image.Image.

####
to_string

< source >

( )

Returns the stringified version of that object. In the case of an AgentImage, it is a path to the serialized version of the image.

###
AgentAudio

###
class smolagents.AgentAudio

< source >

( value samplerate = 16000 )

Audio type returned by the agent.

####
to_raw

< source >

( )

Returns the “raw” version of that object. It is a `torch.Tensor` object.

####
to_string

< source >

( )

Returns the stringified version of that object. In the case of an AgentAudio, it is a path to the serialized version of the audio.

Update on GitHub