smolagents is Hugging Face’s agent library, and its core idea is simple: an agent reasons better when it writes its actions as Python code instead of filling in JSON objects. With under a thousand lines of logic and support for almost any model, it is one of the fastest ways to stand up an agent that actually does things. This guide explains what it is, how its CodeAgent works and when to pick it over a bigger framework. The same explanation is available in Spanish.

Key takeaways

  • smolagents is an open-source library (Apache-2.0 license) whose agent logic fits in under a thousand lines; version 1.26.0 was released on 29 May 2026.
  • Its CodeAgent writes actions as executable Python code, which according to Hugging Face cuts steps (and therefore model calls) by around 30% compared with JSON-based tool calling.
  • It is model-agnostic: it works with the Hugging Face inference API, with OpenAI or Anthropic via LiteLLM, and with models you run on your own machine through Transformers or Ollama.
  • Tools can come from a @tool decorator, from LangChain, from an MCP server or from a Hub Space.
  • To run the generated code safely it offers sandboxed environments with E2B, Docker, Modal or Blaxel.

What is smolagents?

smolagents is a Python library built by Hugging Face to create and run AI agents with very little code. The team calls it "a barebones library for agents that think in code", and that phrase sums up its philosophy: keep abstractions minimal above raw code. The agent core is under a thousand lines in a single file, unlike the layers of classes in other frameworks.

The project is open (Apache-2.0), has over 28,000 GitHub stars and moves fast: version 1.26.0 dates from 29 May 2026. It is not a closed product or a paid service, but a dependency you install and fully control. If you come from wiring an agent loop by hand, as in the Anthropic SDK tutorial, smolagents spares you that boilerplate without hiding what happens inside.

Installing it is one line:

pip install 'smolagents[toolkit]'

The toolkit extra adds default tools, such as web search. From there, everything revolves around two agent types and the freedom to pick the model.

Agents that write code (CodeAgent)

The distinctive piece of smolagents is the CodeAgent. At each step of the reason-act-observe loop, the model does not return JSON with a tool name and its arguments; it returns a block of Python code. That block runs and its result flows back to the model as the next observation. Calling a tool is simply invoking a Python function.

The advantage is composability. In code you can nest calls, use loops and conditionals, store a result in a variable and reuse it, all in a single action. With JSON you would need one step and one model call per operation. Hugging Face argues this approach yields around 30% fewer steps and better performance on hard tasks, an idea that comes from the paper "Executable Code Actions Elicit Better LLM Agents" (CodeAct), which measured up to a 20% higher success rate when acting with code instead of structured text.

If you prefer the classic paradigm, there is also ToolCallingAgent, which uses the usual JSON tool calling. It suits cases where the model has very well-tuned function calling or where your tools are simple and need no chaining.

Tools and models (local or API)

smolagents is model-agnostic: it ties you to no provider. You pick the model class based on where you want to run inference.

  • InferenceClientModel: uses the inference providers on the Hugging Face Hub. It is the quickstart default.
  • LiteLLMModel: connects to OpenAI, Anthropic, Gemini and over a hundred providers through LiteLLM. It also serves Ollama with model_id="ollama_chat/llama3.2".
  • TransformersModel: loads an open model and runs it on your own machine with the transformers library.
  • OpenAIServerModel: points at any endpoint compatible with the OpenAI API, including a local server.

For a model you run with Ollama on your own machine, just point LiteLLMModel or OpenAIServerModel at http://localhost:11434. Tools are just as flexible: you define a function and add the @tool decorator, or import a collection from an MCP server with ToolCollection.from_mcp, from LangChain or from a Hub Space.

A minimal example

This is a complete agent. It creates a CodeAgent with a web-search tool and you give it a task; the agent will write and run the Python needed to solve it:

from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool

model = InferenceClientModel()  # default Hub model
agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)

result = agent.run(
    "Find the height of Mount Teide and tell me how many times it fits in Everest."
)
print(result)

The agent will decide on its own to look up both mountains’ heights, do the division in Python and return the number. Defining your own tool is just as direct:

from smolagents import tool

@tool
def price_with_vat(price: float, rate: float = 21.0) -> float:
    """Compute the final price with VAT.

    Args:
        price: base price in euros.
        rate: VAT percentage, 21 by default.
    """
    return round(price * (1 + rate / 100), 2)

You pass the function in the tools list and the agent can call it inside its code.

smolagents versus bigger frameworks

The usual question is when to pick smolagents over LangGraph, LlamaIndex or OpenAI’s Agents SDK. The short answer: smolagents shines when you want an agent that acts by writing code and prefer little ceremony. Being so small, it is easy to read in full and to debug; there are no state graphs or orchestration layers to learn.

Bigger frameworks win when you need workflows with explicit state, complex conditional branches, long-running persistence or heavily structured multi-agent systems. smolagents also does multi-agent (one agent can manage others), but its natural ground is autonomous agents that solve a task by reasoning with code. For generated code, remember to run it in a sandbox, never straight on your server.

Frequently asked questions

Why does an agent write code instead of JSON?

Because code is more expressive. In a single block it can chain several tools, use loops and store intermediate results in variables, which in JSON would demand one step and one model call per operation. According to Hugging Face, acting with code cuts steps by around 30% and improves results on complex tasks.

Do I need a paid API key to use smolagents?

Not necessarily. With InferenceClientModel you use the Hub’s free inference within its limits, and with TransformersModel or Ollama you run an open model on your own machine with no per-token cost. The LiteLLMModel and OpenAIServerModel classes let you move to a paid provider when you need to.

Is it safe for an agent to run the code it generates?

Only if you isolate it. smolagents integrates secure execution environments with E2B, Docker, Modal or Blaxel for exactly this. Running the generated code directly on your machine is risky; always use a sandbox in any real deployment.

Conclusion

smolagents bets on a concrete idea: an agent performs better when it expresses its actions as Python code. That decision, plus a core of under a thousand lines and support for any model, makes it a very practical entry point into agent development. Start with the CodeAgent from the example, give it a useful tool and, when you move to production, wrap execution in a sandbox. To back it with an open model, the natural next step is to learn how to install Ollama on your own machine.

Sources: [1] smolagents documentation[1], [2] smolagents on GitHub[2], [3] Introducing smolagents (Hugging Face blog)[3], [4] Executable Code Actions Elicit Better LLM Agents[4].

Visitas: 0

Sources

  1. smolagents documentation
  2. smolagents on GitHub
  3. Introducing smolagents (Hugging Face blog)
  4. Executable Code Actions Elicit Better LLM Agents

Route: Frameworks to Build AI Agents