
smolagents
A deliberately small agent library whose agents act by writing Python, not by emitting JSON
What is smolagents?
The central idea is the CodeAgent: rather than returning a structured tool call, the model writes a short Python snippet that calls your tools directly, so nesting a call inside a loop or a conditional comes from the language itself instead of from framework machinery. The whole agent loop is about a thousand lines, which is both the appeal and the ceiling — durable state, workflow definitions and persistence are things you build yourself. A conventional ToolCallingAgent is included for the JSON style where that fits better.
What can you do with smolagents?
- A working agent in four lines — After pip install with the toolkit extra, constructing a CodeAgent with a model and calling run on it is a complete program; there is no project scaffold, config file or graph to declare first.
- Let the model write Python instead of JSON — CodeAgent asks the model for executable Python that calls your tools. Composition you would otherwise need framework features for — a tool call inside a loop, a result fed straight into the next call — is just ordinary code.
- Run that code where it cannot hurt you — Because the model's output is executed, the library supports running it inside Docker or a remote sandbox such as E2B, Modal or Blaxel rather than in your own interpreter.
- Bring tools from where they already live — Tool collections can be loaded from any MCP server, existing LangChain tools can be wrapped, and a Hugging Face Space can be used directly as a tool.
- Point it at any model — Hosted inference providers, OpenAI or Anthropic through LiteLLM, and local models via Transformers or Ollama are all selected by swapping the model object — the agent code above it does not change.
Before you choose smolagents
- Executing model-written Python is the design, not an option, and the default local executor is not a security boundary; the project's own guidance is to move to Docker or a remote sandbox before it touches anything real.
- The small size is a deliberate ceiling: there is no durable state, no workflow definition and no built-in persistence, so a long-running or resumable agent means building that layer yourself.
Star history
21 Aug to 30 Oct · +1.2k
Frequently asked questions
Is smolagents free for commercial use?
smolagents is released under the Apache-2.0 licence — OSI-approved open source, which permits commercial use.
How can smolagents be deployed?
smolagents is available as Self-hosted / Runs locally.