Building Powerful AI Agents with smolagents: A Minimalist Approach

On this page
smolagents is a minimal Python library from Hugging Face
for building AI agents in a few lines of code. Its core agent logic fits in
about 1,000 lines, and its CodeAgent writes its actions as Python code
instead of JSON tool calls. This post shows how to run a first smolagents
agent, how code agents work, how to sandbox their code, and which practices
and settings make agents more reliable.
If you've followed our previous posts on AI agents, you know we think frameworks often add unnecessary complexity to what should be a straightforward process. We've shown how to build agents from scratch without frameworks, but sometimes a minimal abstraction layer saves you from writing the same boilerplate over and over. That's the gap smolagents fills.
Update (November 2026): The code below targets smolagents 1.11 (March 2025). Since then, HfApiModel was renamed to InferenceClientModel in 1.14 and the old name has been removed, OpenAIServerModel is now called OpenAIModel (the old name still works as an alias), and DuckDuckGoSearchTool needs the toolkit extra: pip install "smolagents[openai,toolkit]". Claude 3 Opus, used in the model example, was retired on January 5, 2026, so put a current model ID there. The smolagents releases list all changes.
What makes smolagents different
Many frameworks hide the core agent functionality behind layers of abstraction. smolagents keeps things simple. The entire agent logic fits in ~1,000 lines of code, so you can inspect it and understand what's happening under the hood.
Code execution is a first-class feature: agents write actions as Python code snippets rather than structured tool calls (more on that below). smolagents is model-agnostic and works with virtually any LLM from OpenAI, Anthropic, Hugging Face, or local models. It handles text, vision, video and even audio inputs, similar to what we explored in our analyzing images with GPT-4o guide. And it can use tools from LangChain (which you can generate from any Python SDK), Anthropic's MCP (see our guide on building an MCP server with FastMCP), or even Hugging Face Spaces.
Let's see in practice how smolagents balances simplicity and power.
Getting started with smolagents
To warm up, let's run a simple agent.
First, install the package with the OpenAI extra:
Then define your agent, give it the tools it needs, and run it:
That's it! The agent will:
- Parse the question
- Decide to search for New York's population today and in 1980
- Write and execute Python code to calculate the answer
- Return a complete, well-reasoned response
Note: By default, smolagents prints a lot of debug information, which
helps you understand what's happening at each step. You can turn it down
by setting verbosity_level=LogLevel.ERROR in the agent constructor.
How smolagents code agents work, and why they beat JSON tool calls
Traditional agents use structured JSON for tool calls. The smolagents
CodeAgent writes its actions as Python code snippets instead. Code is
particularly handy when an agent works with complex data structures, like
the ones we dealt with when creating knowledge graphs with Neo4j.
For example, if your question was about the speed of a leopard and the
length of the Pont des Arts bridge in Paris, the agent might generate code
like this:
Research shows that code actions:
- Use 30% fewer steps (and thus 30% fewer LLM calls)
- Achieve higher performance on difficult benchmarks
- Provide more flexibility in how tools are used
See here ("Executable Code Actions Elicit Better LLM Agents"), here ("DynaSaur: Large Language Agents Beyond Predefined Actions") and here ("If LLM Is the Wizard, Then Code Is the Wand", a survey on how code empowers LLM agents).
Security options for code execution in smolagents
Executing LLM-generated code can be (well, is) a security concern, so smolagents gives you several options:
- A secure Python interpreter that runs code more safely in your own environment. Hugging Face wrote a new, restricted Python interpreter that only allows importing whitelisted modules, and even only whitelisted submodules. This is the default behavior.
- Sandboxed environments using E2B or Docker, which execute the agent code
in remote, more isolated environments. You pick one with the
executor_typeargument. - The ability to review code before execution.
smolagents compared with raw implementations and large frameworks
If you've read our previous post on building agents from scratch, you might wonder why use a framework at all. It comes down to balance:
| Approach | Pros | Cons |
|---|---|---|
| Raw Implementation | Complete control, No dependencies | Repetitive boilerplate, Reinventing the wheel |
| smolagents | Minimal abstraction, Transparent code, Flexible | Small learning curve |
| Large Frameworks | Many pre-built components | Complex abstractions, Hard to debug, Less flexible |
smolagents handles the non-trivial parts (like keeping code formats consistent across the system prompt, the parser and the execution) and keeps everything else transparent and accessible.
The Microsoft Agent Framework sits at the other end of the scale: more structure, plus OpenTelemetry tracing, durable workflows and Entra ID authentication for enterprise deployments.
Model compatibility of smolagents
smolagents works with virtually any LLM. Anthropic and Ollama models go
through LiteLLMModel, which needs pip install "smolagents[litellm]":
Sharing smolagents agents on the Hugging Face Hub
One of the most useful features of smolagents is that you can share your agents on the Hugging Face Hub:
The smolagents command line interface
smolagents also ships two CLI commands, smolagent for general-purpose
agents and webagent for web browsing:
Note: To run the web agent, you need to install the helium package.
Best practices for building effective agents with smolagents
A few principles make a big difference in how well smolagents agents perform. We cover more of them in building high-quality AI agent systems.
Simplify your agent workflow
The best agentic systems are often the simplest ones. Giving an LLM agency introduces some risk of errors, so keep the workflow simple.
Reduce the number of LLM calls. Whenever possible, group multiple tools into one: instead of separate "travel distance API" and "weather API" calls, create a single "return_spot_information" function.
Prefer deterministic functions over agentic decisions where you can. That lowers costs, latency and error risk at the same time.
Improve the information flow to the LLM
Think of your LLM engine as an intelligent robot trapped in a room, with notes passed under the door as its only contact with the outside world. It won't know anything you don't explicitly tell it.
For example, here's a poorly designed weather tool:
And here's a better version:
The improved version states the expected input formats, handles errors better and returns a structured output.
Tips when working with smolagents
Enable planning mode
smolagents has a planning feature that lets agents reflect on their progress and plan their next steps:
This adds a planning step in which the LLM updates its knowledge and reflects on the next steps, without making any tool calls.
Reduce logging output
By default, smolagents logs a lot of information to help you understand what's happening at each step. If that's too much, reduce the verbosity level:
Console logs help during development. In production, Langfuse's smolagents integration records each agent step as a trace; our Langfuse guide covers setting up Langfuse itself.
Change the final answer output format
A smolagents agent uses the FinalAnswerTool to generate the final,
user-facing answer. By default, this tool tries to produce a natural language
answer. However, we found that the LLM sometimes answered with a JSON object.
Changing the output format is easy:
Streaming the agent output
LLM outputs are generally slow, so chat applications often stream the answer as it is generated. The user sees a response immediately, even though the full answer isn't available yet.
smolagents can stream the output too. Set the stream parameter to True
and you get a generator that yields each step (planning and action steps) as
soon as it finishes, followed by the final answer:
Interested in building high-quality AI agent systems?
We prepared a comprehensive guide based on cutting-edge research for how to build robust, reliable AI agent systems that actually work in production. This guide covers:
- Understanding the 14 systematic failure modes in multi-agent systems
- Evidence-based best practices for agent design
- Structured communication protocols and verification mechanisms
Conclusion
smolagents strikes a good balance between simplicity and power. It handles the tricky parts of agent development, such as prompt, parser and execution formats, while keeping everything transparent.
Its code-based actions make agents more flexible and efficient than structured tool calls, with fewer steps and higher success rates on hard benchmarks.
If larger frameworks frustrate you, or you're tired of writing the same
boilerplate for every agent project, smolagents is worth a try. Start with
the CodeAgent example above, then add planning and a sandbox once the agent
does real work.
Further reading
-
How to Build AI Agents Without Frameworks - Learn how to build AI agents without frameworks for complete control and understanding
-
Enhancing Self-Made Agent with Memory - Discover how to extend your agents with memory capabilities for more coherent conversations
-
AI Agents with n8n - Explore another lightweight approach to building AI agents using n8n workflow automation
-
DSPy prompt optimization - Optimize the prompts of an LLM pipeline automatically against a metric



