Smolagents: A Long List of Example Usage
Summary
smolagents is Hugging Face’s open-source library for building agents in a few lines of Python. It’s the agent framework I use on this blog.
What is an agent? A program where an LLM decides what happens next. You give it a task and a set of tools. It works in a loop: think, call a tool, look at the result, and repeat until it has an answer.
When should you use an agent? When the path to the answer isn’t known in advance. For example: “research this topic”, “fix this failing test”, “answer a question that may need three searches or may need none”. If you can write the steps down as a fixed pipeline, write the pipeline. It will be cheaper, faster and easier to debug than an agent.
Why smolagents?
- It’s small. The core logic is readable in an afternoon, so you can see exactly what your agent is doing.
- Code agents. Its main agent,
CodeAgent, writes its actions as Python code instead of JSON tool calls. That lets it use loops, conditionals and nested tool calls in a single step. - It works with any model: Hugging Face Inference Providers, OpenAI, Anthropic and others through LiteLLM, local Transformers models or Ollama.
- Tools from anywhere: your own functions, MCP servers, LangChain tools and Hugging Face Spaces.
The rest of this post is the list of examples. Each one is self-contained, so you can copy any of them and run it.
smolagents is still marked as an experimental API that may change. These examples follow the current docs. If something breaks after an upgrade, check the reference first.
Installation
pip install smolagents # core
pip install 'smolagents[toolkit]' # default tools such as web search
pip install 'smolagents[litellm]' # OpenAI, Anthropic, Ollama, etc. through LiteLLM
pip install 'smolagents[transformers]' # local Hugging Face models
pip install 'smolagents[mcp]' # MCP server tools
For Hugging Face Inference models, set your token:
export HF_TOKEN=hf_...
1. The Smallest Possible Agent
from smolagents import CodeAgent, InferenceClientModel
model = InferenceClientModel() # default Hugging Face model
agent = CodeAgent(tools=[], model=model)
result = agent.run("Calculate the sum of numbers from 1 to 10")
print(result)
Even with no tools, a CodeAgent can solve this. It writes and runs Python to do the arithmetic.
2. Choosing a Model Backend
Every agent takes a model. Change the backend and nothing else in your code needs to change.
Hugging Face Inference Providers
from smolagents import InferenceClientModel
model = InferenceClientModel(
model_id="meta-llama/Llama-3.3-70B-Instruct",
provider="together", # optional: pick a specific inference provider
)
OpenAI
from smolagents import OpenAIModel
model = OpenAIModel(model_id="gpt-5") # reads OPENAI_API_KEY
Anthropic, Gemini and 100+ others through LiteLLM
from smolagents import LiteLLMModel
model = LiteLLMModel(model_id="anthropic/claude-sonnet-5-5") # reads ANTHROPIC_API_KEY
Local models through Ollama
from smolagents import LiteLLMModel
model = LiteLLMModel(
model_id="ollama_chat/qwen2.5-coder:14b",
api_base="http://localhost:11434",
)
Local models through Transformers
from smolagents import TransformersModel
model = TransformersModel(model_id="Qwen/Qwen2.5-Coder-7B-Instruct")
Tip: CodeAgent needs a model that writes good Python. Small models work much better with a coding-tuned checkpoint.
3. Built-in Tools
from smolagents import CodeAgent, InferenceClientModel, WebSearchTool
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel())
agent.run("Who won the most recent Tour de France, and by how much?")
Pass add_base_tools=True to give the agent the default toolbox (web search, a Python interpreter and so on) without listing each tool:
agent = CodeAgent(tools=[], model=InferenceClientModel(), add_base_tools=True)
agent.run("Could you give me the 118th number in the Fibonacci sequence?")
4. Writing Your Own Tool with @tool
This is the example you’ll use most often. Any function can become a tool.
from huggingface_hub import list_models
from smolagents import CodeAgent, InferenceClientModel, tool
@tool
def model_download_tool(task: str) -> str:
"""
Returns the most downloaded model on the Hugging Face Hub for a given task.
Args:
task: The task to look up, e.g. "text-classification" or "depth-estimation".
"""
model = next(iter(list_models(filter=task, sort="downloads", direction=-1)))
return model.id
agent = CodeAgent(tools=[model_download_tool], model=InferenceClientModel())
agent.run("What is the most downloaded text-to-video model on the Hub?")
The LLM only sees the tool’s name, type hints and docstring, so those are your prompt. The rules:
- Use a clear, descriptive function name.
- Put type hints on every argument and on the return value.
- Write a description, then an
Args:section that describes every argument.
5. Writing a Tool as a Class
Use a Tool subclass when the tool needs setup, such as loading a model or opening a connection once instead of on every call.
from smolagents import Tool
class HFModelDownloadsTool(Tool):
name = "model_download_counter"
description = "Returns the most downloaded model on the Hugging Face Hub for a given task."
inputs = {
"task": {
"type": "string",
"description": "The task category, e.g. text-classification or depth-estimation",
}
}
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
Valid types for inputs and output_type: string, boolean, integer, number, image, audio, array, object, any, null.
If you plan to share a tool on the Hub, put all imports inside its methods.
6. CodeAgent vs ToolCallingAgent
smolagents has two agent types:
CodeAgent |
ToolCallingAgent |
|
|---|---|---|
| Actions are written as | Python code | JSON tool calls |
| Can loop, branch and chain tools in one step | Yes | No |
| Runs model-generated code | Yes, so sandbox it (see 8) | No |
| Best for | Multi-step reasoning, data work | Simple tool routing, strict environments |
from smolagents import ToolCallingAgent, WebSearchTool, InferenceClientModel
agent = ToolCallingAgent(tools=[WebSearchTool()], model=InferenceClientModel())
agent.run("What is the title of the page at https://huggingface.co/blog?")
Start with CodeAgent. Switch to ToolCallingAgent when you can’t allow generated code to run, or when your model is poor at writing Python.
7. Letting the Agent Import Libraries
By default a CodeAgent can only import a safe list of modules. Allow more explicitly:
from smolagents import CodeAgent, InferenceClientModel
agent = CodeAgent(
tools=[],
model=InferenceClientModel(),
additional_authorized_imports=["requests", "bs4", "pandas", "numpy.*"],
)
agent.run("Get the title of the page at https://huggingface.co/blog")
Submodules are blocked unless you name them. "numpy.*" allows numpy and all its subpackages.
Warning: the model writes arbitrary code, and you are agreeing to run it. Never authorize
os,subprocessor similar on the local executor.
8. Sandboxed Code Execution
The default executor runs generated code on your machine. That’s fine for experiments, but don’t do it with untrusted input or in production. Use a sandbox instead:
from smolagents import CodeAgent, InferenceClientModel
model = InferenceClientModel()
agent = CodeAgent(tools=[], model=model, executor_type="docker") # local Docker container
agent = CodeAgent(tools=[], model=model, executor_type="e2b") # needs E2B_API_KEY
agent = CodeAgent(tools=[], model=model, executor_type="modal") # Modal
agent = CodeAgent(tools=[], model=model, executor_type="blaxel") # needs BL_API_KEY, BL_WORKSPACE
The only change is one argument. There’s no reason not to use one.
9. Passing Data into a Run
Use additional_args to give the agent real Python objects, such as DataFrames, file paths or images, instead of pasting them into the prompt:
import pandas as pd
from smolagents import CodeAgent, InferenceClientModel
sales = pd.read_csv("sales.csv")
agent = CodeAgent(
tools=[],
model=InferenceClientModel(),
additional_authorized_imports=["pandas"],
)
agent.run(
"Which region had the biggest month-on-month growth? The data is in `sales`.",
additional_args={"sales": sales},
)
Give the variables clear names. The agent sees them by name.
10. Multi-Agent: A Manager with a Specialist
Any agent with a name and a description can be handed to another agent as if it were a tool:
from smolagents import CodeAgent, InferenceClientModel, WebSearchTool
model = InferenceClientModel()
web_agent = CodeAgent(
tools=[WebSearchTool()],
model=model,
name="web_search_agent",
description="Runs web searches for you. Give it your query as an argument.",
)
manager = CodeAgent(tools=[], model=model, managed_agents=[web_agent])
manager.run("Who is the CEO of Hugging Face, and what did they announce most recently?")
The description goes into the manager’s system prompt, so write it as carefully as a tool docstring.
11. Tools from an MCP Server
Any MCP server can supply tools to your agent.
A local (stdio) server
import os
from mcp import StdioServerParameters
from smolagents import CodeAgent, InferenceClientModel, MCPClient
model = InferenceClientModel()
server = StdioServerParameters(
command="uvx",
args=["--quiet", "pubmedmcp@0.1.3"],
env={"UV_PYTHON": "3.12", **os.environ},
)
with MCPClient(server, structured_output=True) as tools:
agent = CodeAgent(tools=tools, model=model)
agent.run("Find the latest research on treatments for migraine.")
A remote (HTTP) server
with MCPClient({"url": "http://127.0.0.1:8000/mcp", "transport": "streamable-http"}) as tools:
agent = CodeAgent(tools=tools, model=model)
agent.run("...")
Several servers at once
with MCPClient([server, {"url": "http://127.0.0.1:8000/sse"}]) as tools:
agent = CodeAgent(tools=tools, model=model)
Set structured_output=True explicitly. The default is False today, but the docs say it will change.
Security: stdio servers run code on your machine. Only use MCP servers you trust.
12. Tools from Hugging Face Spaces, the Hub and LangChain
A Gradio Space as a tool
from smolagents import CodeAgent, InferenceClientModel, Tool
image_generator = Tool.from_space(
"black-forest-labs/FLUX.1-schnell",
name="image_generator",
description="Generate an image from a prompt",
)
agent = CodeAgent(tools=[image_generator], model=InferenceClientModel())
agent.run(
"Improve this prompt, then generate an image of it.",
additional_args={"user_prompt": "A rabbit wearing a space suit"},
)
A tool someone shared on the Hub
from smolagents import load_tool
tool = load_tool("{username}/hf-model-downloads", trust_remote_code=True)
A LangChain tool
from langchain.agents import load_tools
from smolagents import Tool
search_tool = Tool.from_langchain(load_tools(["serpapi"])[0])
trust_remote_code=True means exactly that: you are running someone else’s code. Read it first.
13. Controlling the Loop: Steps, Planning and Instructions
from smolagents import CodeAgent, InferenceClientModel, WebSearchTool
agent = CodeAgent(
tools=[WebSearchTool()],
model=InferenceClientModel(),
max_steps=8, # default is 20; cap cost and runaway loops
planning_interval=3, # write or update a plan every 3 steps
instructions="Always cite the URL you got each fact from.",
)
agent.run("Compare the licences of the three most popular open-weight LLMs.")
agent.run("Quick question: what's 17 * 23?", max_steps=2) # override for one run
planning_interval makes a noticeable difference on longer tasks. The agent steps back and revises its plan instead of drifting.
14. Streaming Steps as They Happen
for step in agent.run("Find three recent papers on speculative decoding", stream=True):
print(type(step).__name__, step)
With stream=True, run() returns a generator that yields each step. You must iterate over it, or nothing runs. Pass stream_outputs=True to the agent constructor to also stream the model’s tokens.
15. Step Callbacks: Logging, Monitoring, Intervening
A callback runs after every step. Use one for logging, cost tracking or modifying memory.
from smolagents import ActionStep, CodeAgent, InferenceClientModel
def log_step(step: ActionStep, agent: CodeAgent) -> None:
print(f"Step {step.step_number}: {step.observations!r:.200}")
agent = CodeAgent(
tools=[],
model=InferenceClientModel(),
step_callbacks=[log_step],
)
agent.run("What is 2 to the power 3.7384?")
You can also pass a dict mapping step types to callbacks, so you only react to particular kinds of step.
16. Validating the Final Answer
Reject answers that don’t meet your requirements. The agent logs the failure and keeps working.
def is_integer(final_answer, *args, **kwargs) -> bool:
return isinstance(final_answer, int)
agent = CodeAgent(
tools=[],
model=InferenceClientModel(),
final_answer_checks=[is_integer],
)
agent.run("How many prime numbers are there below 1000?")
This is a cheap way to enforce output contracts, such as a valid JSON shape, a number in a range or a non-empty list.
17. Memory, Multi-Turn Conversations and Replay
agent.run("Find the population of Ireland.")
agent.run("Now compare it with Denmark.", reset=False) # keeps the previous run's memory
agent.replay() # pretty-print every step of the last run
agent.replay(detailed=True) # include memory at each step (verbose, for debugging)
messages = agent.write_memory_to_messages() # memory as chat messages
replay() is the first thing to try when an agent gives a strange answer. You see exactly what code it wrote and what each tool returned.
18. A Chat UI in One Line
from smolagents import CodeAgent, GradioUI, InferenceClientModel, WebSearchTool
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel())
GradioUI(agent).launch()
Each message continues the same conversation. To let users stop a long run, wire a button to agent.interrupt(). It stops at the end of the current step.
19. Sharing Agents and Tools on the Hub
agent.push_to_hub("{username}/my_agent")
tool.push_to_hub("{username}/hf-model-downloads")
from smolagents import CodeAgent
agent = CodeAgent.from_hub("{username}/my_agent", trust_remote_code=True)
20. Running Agents from the Command Line
smolagents installs two commands, smolagent and webagent, that run an agent without any boilerplate. Run smolagent --help for the options. They’re handy for trying a model or a tool before writing any code.
Where to Go Next
- Building good agents: the most useful page in the docs. Read it before your first serious agent.
- Tools tutorial: MCP, Spaces and LangChain in depth.
- Secure code execution: the sandbox options in detail.
- Agents reference: every constructor and
run()parameter. - smolagents on GitHub