Smolagents
Smolagents is a small open-source Python library from Hugging Face for building AI agents, including ones that act by writing short pieces of Python code.
Smolagents is a Python library (a ready-made bundle of code) from Hugging Face for building AI agents. An agent is a program where a language model decides the next step, such as searching the web or doing a sum. Many agent tools ask the model to write each action as JSON, a structured text format: a tool name and its arguments. Smolagents’ main agent works another way. With its main agent type, the CodeAgent, each step the model takes is a short Python program, called a snippet.
That matters because code can do several things at once. One snippet can call a search tool, loop over the results and add them up. JSON calls are hard to nest or reuse like that. The library also stays small and close to plain code. It works with hosted models and with models running on your own computer.
A run is a loop. Your task goes into the agent’s memory. The memory is sent to the model, which replies with a snippet. Smolagents runs the snippet, saves the result, and asks the model again. Say the task is to add the numbers from 1 to 10. The model might write a short line of Python such as sum(range(1, 11)), the code runs, and the agent returns the answer. By default the code runs in a rebuilt Python interpreter (the part that runs Python code), not the normal one. It blocks extra code libraries you have not allowed. It also caps how many operations a snippet can run.
For engineers: every agent builds on one MultiStepAgent class based on ReAct, a pattern that alternates reasoning and acting. A ToolCallingAgent uses JSON calls instead, which can suit tasks like web browsing. The code-as-action idea comes from the CodeAct paper, where code actions reached up to 20 percent higher success across 17 models. The project also reports about 30 percent fewer steps than JSON calls. You turn a Python function into a tool with the @tool decorator, a one-line label placed above it. For stronger isolation, the docs point to Docker or a remote sandbox (a sealed-off computer) such as E2B, chosen with a setting like executor_type docker.
Giving a language model the power to act usually means extra plumbing.
Follow one task through a CodeAgent.
- 1 · logThe system prompt and your task are stored in the agent's memory.
- 2 · askThe memory is turned into chat messages and sent to the model.
- 3 · writeThe model replies with an action, which for a CodeAgent is a Python snippet.
- 4 · runSmolagents runs the snippet and saves the result to memory as an observation.
- 5 · stopThe loop repeats until the code calls final_answer or the step limit is reached.
In smolagents, the model's action is code that gets run, not just text.
| Who | What they ask | What it works with |
|---|---|---|
| Data analyst | “Which customers ordered more than twice last month?” | A text-to-SQL tool the agent calls from its code |
| Support team | “What does our help centre say about refunds?” | A search tool over the team's own documents |
| Researcher | “How long would a leopard take to cross this bridge?” | A web search tool the agent calls from its code |
| Hobby developer | “Can I run the same agent on a local model?” | The model setting, swapped from a hosted API to a local one |
- The core agent logic is small, about a thousand lines of code.
- Code actions can nest tool calls, loop and branch in one step.
- The same agent can run on hosted APIs or on local models.
- Tools can come from MCP servers, LangChain or Hugging Face Spaces.
- Running model-written code on your machine is risky, and no local sandbox is fully secure.
- Stronger isolation, such as Docker or a remote sandbox, takes extra setup.
- For a task with a fixed, known workflow, an agent is often more than you need.
- The model can still write harmful commands by mistake.
Sources used
This explainer is written in original language. The links below support its factual claims.
- docssmolagents, Hugging Face · read 28 Sept 2026
- repohuggingface/smolagents, Hugging Face on GitHub · read 28 Sept 2026
- docsHow do multi-step agents work?, Hugging Face · read 28 Sept 2026
- docsSecure code execution, Hugging Face · read 28 Sept 2026
- officialIntroducing smolagents: simple agents that write actions in code, Hugging Face · read 28 Sept 2026
- paperExecutable Code Actions Elicit Better LLM Agents, Wang et al., ICML 2024 · read 28 Sept 2026
- docsGuided tour, Hugging Face · read 28 Sept 2026