#
Tools

Smolagents एक experimental API है जो किसी भी समय बदल सकता है। एजेंट्स द्वारा लौटाए गए परिणाम भिन्न हो सकते हैं क्योंकि APIs या underlying मॉडल बदलने की संभावना रखते हैं।

एजेंट्स और टूल्स के बारे में अधिक जानने के लिए introductory guide पढ़ना सुनिश्चित करें। यह पेज underlying क्लासेज के लिए API docs को शामिल करता है।

##
Tools

###
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`.

##
Default Tools

###
PythonInterpreterTool

###
class smolagents.PythonInterpreterTool

< source >

( *args authorized_imports = None **kwargs )

###
DuckDuckGoSearchTool

###
class smolagents.DuckDuckGoSearchTool

< source >

( max_results: int = 10 rate_limit: float | None = 1.0 **kwargs )

Parameters

- max_results (`int`, default `10`) — Maximum number of search results to return.
- rate_limit (`float`, default `1.0`) — Maximum queries per second. Set to `None` to disable rate limiting.
- **kwargs — Additional keyword arguments for the `DDGS` client.

Web search tool that performs searches using the DuckDuckGo search engine.

Examples:

    >>> from smolagents import DuckDuckGoSearchTool
    >>> web_search_tool = DuckDuckGoSearchTool(max_results=5, rate_limit=2.0)
    >>> results = web_search_tool("Hugging Face")
    >>> print(results)

###
VisitWebpageTool

###
class smolagents.VisitWebpageTool

< source >

( max_output_length: int = 40000 )

###
UserInputTool

###
class smolagents.UserInputTool

< source >

( *args **kwargs )

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

> [!NOTE] 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.")

##
Agent टाइप्स

एजेंट्स टूल्स के बीच किसी भी प्रकार की ऑब्जेक्ट को संभाल सकते हैं; टूल्स, पूरी तरह से मल्टीमोडल होने के कारण, टेक्स्ट, इमेज, ऑडियो, वीडियो सहित अन्य प्रकारों को स्वीकार और रिटर्न कर सकते हैं। टूल्स के बीच अनुकूलता बढ़ाने के साथ-साथ इन रिटर्न्स को ipython (jupyter, colab, ipython notebooks, …) में सही ढंग से रेंडर करने के लिए, हम इन टाइप्स के आसपास रैपर क्लासेज को लागू करते हैं।

रैप किए गए ऑब्जेक्ट्स को प्रारंभ में जैसा व्यवहार करना चाहिए वैसा ही करना जारी रखना चाहिए; एक टेक्स्ट ऑब्जेक्ट को अभी भी स्ट्रिंग की तरह व्यवहार करना चाहिए| एक इमेज ऑब्जेक्ट को अभी भी `PIL.Image` की तरह व्यवहार करना चाहिए।

इन टाइप्स के तीन विशिष्ट उद्देश्य हैं:

- टाइप पर `to_raw` को कॉल करने से अंतर्निहित ऑब्जेक्ट रिटर्न होना चाहिए
- टाइप पर `to_string` को कॉल करने से ऑब्जेक्ट को स्ट्रिंग के रूप में रिटर्न होना चाहिए: वह `AgentText` के मामले में स्ट्रिंग हो सकती है लेकिन अन्य उदाहरणों में ऑब्जेक्ट के सीरियलाइज्ड वर्जन का पाथ होगा
- इसे एक ipython kernel में प्रदर्शित करने पर ऑब्जेक्ट को सही ढंग से प्रदर्शित करना चाहिए

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