← Back to all projects

smolagents

A deliberately small agent library whose agents act by writing Python, not by emitting JSON

OfficialApache-2.0
Stars
30.1k
Forks
3.2k
Open issues
1k
Last commit
29 Oct 2026

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

28.9k30.1k

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.