- \n
- Tools<\/a>\n
- \n
- What is a tool, and how to build one?<\/a><\/li>\n\n\n\n
- Share your tool to the Hub<\/a><\/li>\n\n\n\n
- Import a Space as a tool<\/a><\/li>\n\n\n\n
- Use LangChain tools<\/a><\/li>\n\n\n\n
- Manage your agent\u2019s toolbox<\/a><\/li>\n\n\n\n
- Use a collection of tools<\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n
<\/a>What is a tool, and how to build one?<\/h3>\n\n\n\n
A tool is mostly a function that an LLM can use in an agentic system.<\/p>\n\n\n\n
But to use it, the LLM will need to be given an API: name, tool description, input types and descriptions, output type.<\/p>\n\n\n\n
So it cannot be only a function. It should be a class.<\/p>\n\n\n\n
So at core, the tool is a class that wraps a function with metadata that helps the LLM understand how to use it.<\/p>\n\n\n\n
Here\u2019s how it looks:<\/p>\n\n\n\n
Copied<\/p>\n\n\n\n
from smolagents import Tool\n\nclass HFModelDownloadsTool(Tool):\n name = \"model_download_counter\"\n description = \"\"\"\n This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub.\n It returns the name of the checkpoint.\"\"\"\n inputs = {\n \"task\": {\n \"type\": \"string\",\n \"description\": \"the task category (such as text-classification, depth-estimation, etc)\",\n }\n }\n output_type = \"string\"\n\n def forward(self, task: str):\n from huggingface_hub import list_models\n\n model = next(iter(list_models(filter=task, sort=\"downloads\", direction=-1)))\n return model.id\n\nmodel_downloads_tool = HFModelDownloadsTool()<\/pre>\n\n\n\nThe custom tool subclasses\u00a0Tool<\/a>\u00a0to inherit useful methods. The child class also defines:<\/p>\n\n\n\n
- \n
- An attribute\u00a0
name<\/code>, which corresponds to the name of the tool itself. The name usually describes what the tool does. Since the code returns the model with the most downloads for a task, let\u2019s name it\u00a0model_download_counter<\/code>.<\/li>\n\n\n\n- An attribute\u00a0
description<\/code>\u00a0is used to populate the agent\u2019s system prompt.<\/li>\n\n\n\n- An\u00a0
inputs<\/code>\u00a0attribute, which is a dictionary with keys\u00a0\"type\"<\/code>\u00a0and\u00a0\"description\"<\/code>. It contains information that helps the Python interpreter make educated choices about the input.<\/li>\n\n\n\n- An\u00a0
output_type<\/code>\u00a0attribute, which specifies the output type. The types for both\u00a0inputs<\/code>\u00a0and\u00a0output_type<\/code>\u00a0should be\u00a0Pydantic formats<\/a>, they can be either of these:\u00a0~AUTHORIZED_TYPES()<\/code>.<\/li>\n\n\n\n- A\u00a0
forward<\/code>\u00a0method which contains the inference code to be executed.<\/li>\n<\/ul>\n\n\n\nAnd that\u2019s all it needs to be used in an agent!<\/p>\n\n\n\n
There\u2019s another way to build a tool. In the\u00a0guided_tour<\/a>, we implemented a tool using the\u00a0
@tool<\/code>\u00a0decorator. The\u00a0tool()<\/a>\u00a0decorator is the recommended way to define simple tools, but sometimes you need more than this: using several methods in a class for more clarity, or using additional class attributes.<\/p>\n\n\n\nIn this case, you can build your tool by subclassing\u00a0Tool<\/a>\u00a0as described above.<\/p>\n\n\n\n
<\/a>Share your tool to the Hub<\/h3>\n\n\n\n
You can share your custom tool to the Hub by calling\u00a0push_to_hub()<\/a>\u00a0on the tool. Make sure you\u2019ve created a repository for it on the Hub and are using a token with read access.<\/p>\n\n\n\n
Copied<\/p>\n\n\n\n
model_downloads_tool.push_to_hub(\"{your_username}\/hf-model-downloads\", token=\"<YOUR_HUGGINGFACEHUB_API_TOKEN>\")<\/pre>\n\n\n\nFor the push to Hub to work, your tool will need to respect some rules:<\/p>\n\n\n\n
- \n
- All methods are self-contained, e.g. use variables that come either from their args.<\/li>\n\n\n\n
- As per the above point,\u00a0all imports should be defined directly within the tool\u2019s functions<\/strong>, else you will get an error when trying to call\u00a0save()<\/a>\u00a0or\u00a0push_to_hub()<\/a>\u00a0with your custom tool.<\/li>\n\n\n\n
- If you subclass the\u00a0
__init__<\/code>\u00a0method, you can give it no other argument than\u00a0self<\/code>. This is because arguments set during a specific tool instance\u2019s initialization are hard to track, which prevents from sharing them properly to the hub. And anyway, the idea of making a specific class is that you can already set class attributes for anything you need to hard-code (just set\u00a0your_variable=(...)<\/code>\u00a0directly under the\u00a0class YourTool(Tool):<\/code>\u00a0line). And of course you can still create a class attribute anywhere in your code by assigning stuff to\u00a0self.your_variable<\/code>.<\/li>\n<\/ul>\n\n\n\nOnce your tool is pushed to Hub, you can visualize it.\u00a0Here<\/a>\u00a0is the\u00a0
model_downloads_tool<\/code>\u00a0that I\u2019ve pushed. It has a nice gradio interface.<\/p>\n\n\n\nWhen diving into the tool files, you can find that all the tool\u2019s logic is under\u00a0tool.py<\/a>. That is where you can inspect a tool shared by someone else.<\/p>\n\n\n\n
Then you can load the tool with\u00a0load_tool()<\/a>\u00a0or create it with\u00a0from_hub()<\/a>\u00a0and pass it to the\u00a0
tools<\/code>\u00a0parameter in your agent. Since running tools means running custom code, you need to make sure you trust the repository, thus we require to pass\u00a0trust_remote_code=True<\/code>\u00a0to load a tool from the Hub.<\/p>\n\n\n\nCopied<\/p>\n\n\n\n
from smolagents import load_tool, CodeAgent\n\nmodel_download_tool = load_tool(\n \"{your_username}\/hf-model-downloads\",\n trust_remote_code=True\n)<\/pre>\n\n\n\n<\/a>Import a Space as a tool<\/h3>\n\n\n\n
You can directly import a Space from the Hub as a tool using the\u00a0Tool.from_space()<\/a>\u00a0method!<\/p>\n\n\n\n
You only need to provide the id of the Space on the Hub, its name, and a description that will help you agent understand what the tool does. Under the hood, this will use\u00a0
gradio-client<\/code><\/a>\u00a0library to call the Space.<\/p>\n\n\n\nFor instance, let\u2019s import the\u00a0FLUX.1-dev<\/a>\u00a0Space from the Hub and use it to generate an image.<\/p>\n\n\n\n
Copied<\/p>\n\n\n\n
image_generation_tool = Tool.from_space(\n \"black-forest-labs\/FLUX.1-schnell\",\n name=\"image_generator\",\n description=\"Generate an image from a prompt\"\n)\n\nimage_generation_tool(\"A sunny beach\")<\/pre>\n\n\n\n
And voil\u00e0, here\u2019s your image! \ud83c\udfd6\ufe0f<\/p>\n\n\n\n
![\"\"](\"https:\/\/smolagents.org\/wp-content\/uploads\/2025\/01\/sunny_beach.webp\")
<\/figure>\n\n\n\nThen you can use this tool just like any other tool. For example, let\u2019s improve the prompt
a rabbit wearing a space suit<\/code> and generate an image of it.<\/p>\n\n\n\nCopied<\/p>\n\n\n\n
from smolagents import CodeAgent, HfApiModel\n\nmodel = HfApiModel(\"Qwen\/Qwen2.5-Coder-32B-Instruct\")\nagent = CodeAgent(tools=[image_generation_tool], model=model)\n\nagent.run(\n \"Improve this prompt, then generate an image of it.\", prompt='A rabbit wearing a space suit'\n)<\/pre>\n\n\n\n
Copied<\/p>\n\n\n\n
=== Agent thoughts:\nimproved_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\"\n\nNow that I have improved the prompt, I can use the image generator tool to generate an image based on this prompt.\n>>> Agent is executing the code below:\nimage = 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\")\nfinal_answer(image)<\/pre>\n\n\n\n
![\"\"](\"https:\/\/smolagents.org\/wp-content\/uploads\/2025\/01\/rabbit_spacesuit_flux.webp\")
<\/figure>\n\n\n\nHow cool is this? \ud83e\udd29<\/p>\n\n\n\n
<\/a>Use LangChain tools<\/h3>\n\n\n\n
We love Langchain and think it has a very compelling suite of tools. To import a tool from LangChain, use the
from_langchain()<\/code> method.<\/p>\n\n\n\nHere is how you can use it to recreate the intro\u2019s search result using a LangChain web search tool. This tool will need
pip install langchain google-search-results -q<\/code> to work properly.<\/p>\n\n\n\nCopied<\/p>\n\n\n\n
from langchain.agents import load_tools\n\nsearch_tool = Tool.from_langchain(load_tools([\"serpapi\"])[0])\n\nagent = CodeAgent(tools=[search_tool], model=model)\n\nagent.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?\")<\/pre>\n\n\n\n
<\/a>Manage your agent\u2019s toolbox<\/h3>\n\n\n\n
You can manage an agent\u2019s toolbox by adding or replacing a tool in attribute
agent.tools<\/code>, since it is a standard dictionary.<\/p>\n\n\n\nLet\u2019s add the
model_download_tool<\/code> to an existing agent initialized with only the default toolbox.<\/p>\n\n\n\nCopied<\/p>\n\n\n\n
from smolagents import HfApiModel\n\nmodel = HfApiModel(\"Qwen\/Qwen2.5-Coder-32B-Instruct\")\n\nagent = CodeAgent(tools=[], model=model, add_base_tools=True)\nagent.tools[model_download_tool.name] = model_download_tool<\/pre>\n\n\n\n
Now we can leverage the new tool:<\/p>\n\n\n\n
Copied<\/p>\n\n\n\n
agent.run(\n \"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?\"\n)<\/pre>\n\n\n\n
Beware of not adding too many tools to an agent: this can overwhelm weaker LLM engines.<\/p>\n\n\n\n
<\/a>Use a collection of tools<\/h3>\n\n\n\n
You can leverage tool collections by using the ToolCollection object, with the slug of the collection you want to use. Then pass them as a list to initialize your agent, and start using them!<\/p>\n\n\n\n
Copied<\/p>\n\n\n\n
from smolagents import ToolCollection, CodeAgent\n\nimage_tool_collection = ToolCollection(\n collection_slug=\"huggingface-tools\/diffusion-tools-6630bb19a942c2306a2cdb6f\",\n token=\"<YOUR_HUGGINGFACEHUB_API_TOKEN>\"\n)\nagent = CodeAgent(tools=[*image_tool_collection.tools], model=model, add_base_tools=True)\n\nagent.run(\"Please draw me a picture of rivers and lakes.\")<\/pre>\n\n\n\n
To speed up the start, tools are loaded only if called by the agent.<\/p>","protected":false},"excerpt":{"rendered":"
Here, we\u2019re going to see advanced tool usage. If you\u2019re new to building agents, make sure to first read the\u00a0intro to agents\u00a0and the\u00a0guided tour of smolagents. What is a tool, and how to build one? A tool is mostly a function that an LLM can use in an agentic system. But to use it, the…<\/p>","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"_kadence_starter_templates_imported_post":false,"_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"footnotes":""},"doc_category":[8],"doc_tag":[],"class_list":["post-591","docs","type-docs","status-publish","hentry","doc_category-tutorials"],"year_month":"2026-04","word_count":1431,"total_views":"5628","reactions":{"happy":"0","normal":"0","sad":"0"},"author_info":{"name":"smolagents","author_nicename":"wd-gstargmail-com","author_url":"https:\/\/smolagents.org\/hi\/author\/wd-gstargmail-com\/"},"doc_category_info":[{"term_name":"Tutorials","term_url":"https:\/\/smolagents.org\/hi\/docs-category\/tutorials\/"}],"doc_tag_info":[],"_links":{"self":[{"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/docs\/591","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/comments?post=591"}],"version-history":[{"count":1,"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/docs\/591\/revisions"}],"predecessor-version":[{"id":594,"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/docs\/591\/revisions\/594"}],"wp:attachment":[{"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/media?parent=591"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/doc_category?post=591"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/smolagents.org\/hi\/wp-json\/wp\/v2\/doc_tag?post=591"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
- If you subclass the\u00a0
- An attribute\u00a0
- Share your tool to the Hub<\/a><\/li>\n\n\n\n
- What is a tool, and how to build one?<\/a><\/li>\n\n\n\n