What is smolagents?
Most agent frameworks give agents a menu of pre-defined tools — "search the web", "read a file", "send an email" — and the agent picks which one to call. smolagents takes a different approach: give the agent a code interpreter, and let it write Python to do whatever it needs.
Released in 2024 by Hugging Face, smolagents is built around the insight that code is a universal tool. Instead of defining rigid tool schemas, a CodeAgent can string together Python operations, call libraries, manipulate data structures, and improvise solutions that no predefined tool anticipates. This makes it more flexible than most agent frameworks — at the cost of requiring a secure sandbox for code execution.
"Smol" isn't just a cute name. The core library is genuinely tiny — around 1,000 lines of code — which means it's easy to read, understand, fork, and customize. No framework magic you can't trace.
Key features of smolagents
CodeAgent
The flagship agent type. Instead of outputting JSON tool calls, it writes and executes Python code at each step. Variables persist between steps, making it great for data transformation, multi-step calculation, and creative problem-solving.
ToolCallingAgent
A more traditional agent that calls structured tools via JSON. Useful when you want predictable, controlled tool use without arbitrary code execution. Pick the agent type that fits your use case.
Built-in tools
smolagents ships with commonly needed tools out of the box: web search, Python code interpreter, image generation (via Hugging Face models), speech-to-text, and more. You can also wrap any Python function as a tool with a simple decorator.
Hugging Face Hub integration
Share and reuse tools on the Hugging Face Hub — search for community-built tools, publish your own, and load them in one line. The HF ecosystem means native access to thousands of open models.
Works with any model
Connect to OpenAI, Anthropic Claude, Google Gemini, or any Hugging Face model via the Inference API or locally with Transformers. Model-agnostic by design.
Tiny, readable codebase
The entire core fits in ~1,000 lines. You can read it in an afternoon. This matters when you want to understand what's happening under the hood, debug unexpected behavior, or customize the framework for your needs.
How smolagents works
Here's the core loop for a CodeAgent:
You give the agent a task and a set of tools it can use.
The agent thinks (calls the LLM) and writes a snippet of Python code that uses those tools.
The code runs in a sandboxed interpreter, and the result becomes part of the agent's context.
The agent reflects on the result and either continues (writes more code) or returns its final answer.
Real-life use cases
Research and data gathering
- Search the web for competitor pricing, parse the results with Python, and build a comparison table
- Scrape, clean, and analyze a dataset — all in one agent run
Multi-model pipelines
- An agent that calls one HF model for image captioning, another for translation, and stitches results together
- Agentic pipelines that use Hugging Face's open models instead of paid APIs
Lightweight automation
- Simple task automations where you don't need the overhead of LangChain or CrewAI
- Educational experiments for learning how agents work — the tiny codebase makes it ideal for teaching
Pros and cons
Pros
- Code-first agents are more flexible than tool-calling agents
- Tiny codebase — easy to understand, customize, and trust
- Native Hugging Face Hub integration for tools and models
- Works with both open and proprietary models
- Excellent documentation and tutorials from the HF team
- Fully open source and free
Cons
- Code execution requires a secure sandbox — security risk if misconfigured
- Less mature ecosystem than LangChain or AutoGen
- Fewer third-party integrations and community resources
- CodeAgent requires a capable model — weaker models produce broken code
smolagents pricing
| Component | Cost | Notes |
|---|---|---|
| smolagents library | Free | Apache 2.0 license, open source |
| HF Inference API | Pay per call | Free tier with rate limits available |
| Your own LLM key | Free | OpenAI/Anthropic key or local model via Transformers |
Check huggingface.co/pricing for current Inference API rates.
Alternatives to smolagents
- LangChain Agents — more integrations, more community resources. Heavier framework, but more production-proven.
- AutoGen — also supports code execution, with a richer conversational multi-agent model. More complex but more capable for multi-agent scenarios.
- CrewAI — simpler, role-based multi-agent system. Doesn't use code execution but is much easier to get started with.
- Pydantic AI — a newer, type-safe agent framework. Similar in spirit to smolagents but with a stronger focus on production reliability.
- LangGraph — graph-based agent runtime when you need durable state and human-in-the-loop.
Tips and mistakes to avoid
Tips for using smolagents effectively
- Use a capable model for CodeAgent. Writing correct Python from an LLM requires reasoning ability. GPT-4o, Claude 3.5+, or Qwen2.5-Coder perform well; smaller models often produce broken code.
- Read the source. The whole framework is ~1,000 lines. Spend 30 minutes reading it and you'll understand exactly what your agent is doing.
- Browse the Hub for tools first. Before writing a custom tool, search the Hugging Face Hub — someone may have already shared exactly what you need.
Common mistakes to avoid
- Running CodeAgent without a sandbox in production. If the agent writes and executes arbitrary Python, it needs to run in a container or restricted environment.
- Using a weak model. A model that can't write reliable Python will frustrate you with broken code loops. Always test with a capable model first.
- Writing overly complex tools. The power of CodeAgent is that it can compose simple tools with code. Keep your individual tools focused.