smolagents

Overview

smolagents is a small, open-source Python library from Hugging Face for building agents. Its headline idea is the code agent. Instead of asking the model to emit one structured tool call at a time, a code agent asks the model to write a short Python snippet. The snippet can call several tools, store results in variables, loop over items and do arithmetic, all in one step. The library runs the snippet, shows the model the output, and repeats.

The library is deliberately minimal. Its core agent logic fits in fewer than a thousand lines of code, so you can read it and understand what happens. It works with open models and commercial models alike, and it connects to the Hugging Face Hub, where people share tools and agents.

An everyday comparison is giving instructions to a helper. With a tool-calling agent you say one thing at a time: "Look up the price." "Now look up the tax rate." "Now multiply them." With a code agent you hand over a short written recipe: "Look up the price and tax rate, multiply them, and if the result is over 100, also check the discount." The recipe does more per handover, but you must make sure the helper only works in a safe kitchen.

What it is

smolagents is a Python package licensed under Apache 2.0. It offers two agent types and a set of supporting pieces.

Tools can also come from MCP servers, LangChain or Hugging Face Spaces. Agents accept text and, with suitable models, images, audio and video.

Where it came from

Hugging Face first offered agents inside its Transformers library. On 31 December 2024 it released smolagents as a separate, simpler library to replace that earlier agent code. The name signals the design goal: "smol", internet slang for small.

The library builds on research showing that writing actions as code can help agents. The CodeAct paper (2024) found that executable code actions let models combine tools more flexibly and reach good results in fewer steps. The smolagents documentation cites work suggesting code actions use about 30 per cent fewer steps, and so fewer model calls, than JSON tool calls on the tasks studied. Since release, the project has added more sandbox options, more model adapters, multimodal inputs, MCP tool support and command-line agents.

How it works

Step 1: Define tools

A tool is a function with a name, a description, typed inputs and an output type. The simplest way is to decorate a Python function with @tool and write a clear docstring. The agent sees each tool as a Python function signature with documentation.

Step 2: Choose a model

You pick a model class. For example, one class uses Hugging Face inference providers, another runs a local model with Transformers, another uses LiteLLM to reach many vendors, and another talks to any OpenAI-compatible server.

Step 3: Create the agent and run it

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model)
agent.run("How many seconds would a cheetah at 100 km/h take to cross a 155 m bridge?")

Step 4: The code-action loop

On each step the model writes a short thought and a Python snippet. The executor runs the snippet. Anything printed, and any error, becomes the observation for the next step. The model calls a special final_answer function when it is done. A maximum number of steps stops endless loops.

Because the action is code, one step can do a lot: call a search tool for three cities in a loop, put the results in a dictionary and compute an average. A JSON tool-calling agent would usually need several round trips for the same work.

Step 5: Control where code runs

Running model-written code is a security risk, so where it runs matters.

• The local Python executor is a restricted interpreter. It only allows imports you list, using additional_authorized_imports, and it blocks many dangerous operations. The project states clearly that it is not a security sandbox and must not run untrusted code.
• Remote executors run code in an isolated environment, such as an E2B or Modal sandbox, or a Docker container you control.

See sandboxing for why isolation matters.

Step 6: Combine agents

An agent can be given other agents as helpers. The main agent calls them like tools, passing a task and receiving a report. This is a simple form of the orchestrator-workers pattern.

Key concepts and terms

A worked example

This scenario is illustrative. A data journalist wants quick answers from a folder of public CSV files about air quality.

1. She creates a CodeAgent with two tools: list_files() and load_csv(name), which returns a small table. She allows the pandas and statistics imports.
2. She runs the agent in a Docker container that has only the CSV folder mounted and no network access.
3. She asks: "Which of the 8 cities had the highest average PM2.5 in 2025, and by how much did it exceed the second?"
4. In step one, the agent writes code that lists the files, loads all 8 in a loop and computes yearly means. In step two it sorts the results and finds the top two cities, 31.2 and 27.9, a gap of 3.3. In step three it calls final_answer.
5. Three model calls are enough. A tool-calling design would have needed at least eight load_csv calls before any calculation.
6. She checks the arithmetic against her own spreadsheet before publishing, because the agent's code could contain a subtle mistake.

Strengths and limitations

Strengths:

• Very small and readable codebase.
• Code actions can combine many tools in one step, often reducing model calls.
• Works with open and local models as well as commercial APIs.
• Several remote sandbox options for safe execution.
• Easy sharing of tools and agents through the Hugging Face Hub.
• Supports MCP tools and multimodal inputs.

Limitations:

• Executing model-written code needs a real sandbox; the local executor is not one.
• Code agents need models that write correct Python; small models make more mistakes.
• Fewer built-in production features, such as durable execution or rich workflow control, than larger frameworks.
• Errors in generated code can be subtle, such as wrong units or off-by-one ranges.
• Multi-agent support is simple compared with graph-based frameworks.

How it compares with alternatives

Practical guidance and best practices

1. Use a remote sandbox or container for any agent that runs code on untrusted input.
2. Keep the list of authorised imports as short as possible.
3. Give the sandbox only the files and network access the task needs.
4. Write precise tool docstrings, including units and return formats.
5. Set a sensible maximum number of steps.
6. Prefer ToolCallingAgent when actions are simple, single calls or when the model writes code poorly.
7. Check numerical answers independently for anything you publish or act on.
8. Log every step's code and output so you can audit what ran.

Common mistakes

• Treating the local Python executor as a security boundary.
• Giving the agent broad imports such as os or subprocess without need.
• Using a small model that cannot write reliable Python for complex tasks.
• Writing tool descriptions without units, so the agent mixes kilometres and miles.
• Trusting the final answer without reading the code that produced it.

Frequently asked questions

What is smolagents?

smolagents is a minimal, open-source Python library from Hugging Face for building agents, best known for code agents that write Python snippets as their actions.

What is a code agent?

A code agent writes its actions as Python code that calls tools as functions. One action can call several tools, use variables and loops, and compute results, before the output is shown back to the model.

Is it safe to run model-written code?

Only in a proper sandbox. The built-in local executor restricts imports and operations but is not a security sandbox. Use remote sandboxes or containers for untrusted tasks.

Does smolagents work with open models?

Yes. It can run local models through Transformers and reach open models through Hugging Face inference providers, as well as commercial models through other adapters.

When should I use ToolCallingAgent instead?

Use it when each action is a single, simple tool call, when you cannot sandbox code execution, or when your model is better at structured tool calls than at writing Python. See function calling.

Can smolagents use MCP servers?

Yes. Tools can be loaded from MCP servers, as well as from the Hugging Face Hub, Spaces and LangChain.

Glossary

• Agent: a model that acts in steps to reach a goal.
• Code action: a Python snippet used as an agent's action.
• Tool: a function the agent can call.
• Executor: the runtime for agent code.
• Sandbox: an isolated environment that limits damage.
• Authorised imports: modules the local executor allows.
• Final answer: the call that ends a run.
• Managed agent: a helper agent called by another agent.
• Hugging Face Hub: a platform for sharing machine learning assets.

Summary

smolagents is Hugging Face's minimal agent library, released at the end of 2024. Its code agents write Python snippets as actions, which lets one step combine several tools and often reduces the number of model calls. It works with open and commercial models and shares tools through the Hub. The price of that power is security: run code agents in a real sandbox, keep imports tight, write clear tools and check important results yourself.

Related

It belongs to Frameworks in my stack, under Agentic AI. Others in the same group: