Hugging Face's minimal, code-first agent library concept by concept — what smolagents is, code agents (actions as code), why code actions win, secure sandboxed execution, tools, models, the agent loop and multi-agent systems, and when to use it.
Most agent frameworks have the model call tools by emitting JSON. smolagents, Hugging Face's deliberately tiny library, makes the model write Python code instead — "agents that think in code." That one design choice, plus a ruthless commitment to minimalism, is what the whole library is about, and it turns out to matter more than it sounds.
Most agent frameworks have the model call tools by emitting JSON. smolagents, Hugging Face's deliberately tiny library, makes the model write Python code instead — 'agents that think in code.' That one choice, plus ruthless minimalism, is the whole library.
The single idea that defines smolagents is that an agent's action is a snippet of Python, not a JSON blob. It sounds like a minor encoding detail and turns out to change what an agent can do in a single step — because code carries logic, loops, variables, and composition that structured tool calls simply can't express.
The single idea that defines smolagents is that an agent's action is a snippet of Python, not a JSON blob. It sounds like an encoding detail and turns out to change what an agent can do in one step — because code carries logic, loops, and composition JSON can't.
The claim that agents should write code isn't just aesthetic — Hugging Face backs it with measured results: code agents take fewer steps, make fewer LLM calls, and score better on hard benchmarks. This post examines the evidence and the mechanism, so you understand not just that code actions win but why.
The claim that agents should write code isn't just aesthetic — Hugging Face backs it with measured results: code agents take fewer steps, make fewer LLM calls, and score better on hard benchmarks. This examines the evidence and the mechanism.
The power of code agents comes with a sharp edge: you are executing code written by an LLM, and an LLM can be wrong, or manipulated into writing something harmful. Running that code unsandboxed is one of the most dangerous things you can do in an application, so sandboxing isn't optional for code agents — it's the price of admission.
The power of code agents comes with a sharp edge: you are executing code written by an LLM, which can be wrong or manipulated. Running it unsandboxed is one of the most dangerous things you can do — so sandboxing is the price of admission.
Even an agent that thinks in code needs tools — the functions its code calls to reach beyond itself. smolagents defines them the same minimal way it does everything: a decorated Python function. The twist is that in a code agent, tools are called from within code, which is what makes composing them so natural.
Even an agent that thinks in code needs tools — the functions its code calls. smolagents defines them the same minimal way (a decorated function), and the twist is that tools are called from within code, which is what makes composing them so natural.
A code agent is only as good as the model writing the code — and smolagents, true to its Hugging Face roots and minimalist ethos, lets you run almost any model behind it: open models from the Hub, hosted APIs, local models, anything reachable through its integrations. Model choice matters especially here, because the model's code-writing ability is the agent's ability.
A code agent is only as good as the model writing the code — and smolagents lets you run almost any model: open models from the Hub, hosted APIs, local models. Model choice matters especially here, because the model's code-writing ability is the agent's ability.
Underneath the code-agent magic is a simple, readable loop — the kind of loop smolagents's minimalism lets you actually understand. And when one agent isn't enough, the same minimal parts compose into multi-agent systems, where a manager agent's code calls other agents as if they were tools.
Underneath the code-agent magic is a simple, readable loop that smolagents's minimalism lets you actually understand. And when one agent isn't enough, the same parts compose into multi-agent systems, where a manager agent's code calls other agents like tools.
smolagents is the right choice when you value a small library you can fully understand, the code-agent approach fits your task, and you can execute code safely. It's the wrong choice when you need a big ecosystem, can't sandbox, or your tasks are simple isolated calls. This closing post gives the honest verdict and places smolagents in the landscape.
smolagents is the right choice when you value a small library you can fully understand, the code-agent approach fits your task, and you can execute code safely — and the wrong choice when you need a big ecosystem, can't sandbox, or your tasks are simple isolated calls.
This series is part of a larger body of work by Pratik Dhanave, an Agentic AI Architect writing about production AI systems, distributed systems, and cloud-native engineering. Explore all course series, browse every post, or find topics via the tag index.