smolagents: a barebones Python agent library where the agent writes code

What smolagents is for, and who it is not for

Most agent frameworks ask a model to emit a JSON blob naming a tool and its arguments, then parse that blob. smolagents inverts the pattern. Its CodeAgent writes its actions in Python, and the library executes that Python. The project description in pyproject.toml puts it plainly: "Agents write python code to call tools or orchestrate other agents." The README claims the agent logic fits in roughly 1,000 lines in src/smolagents/agents.py, and that abstractions were kept to a minimal shape above raw code.

That framing tells you the audience. This is for Python engineers who want to read the whole agent loop, not configure it. It suits people building a single-purpose agent over a handful of tools, and people who want to try several model backends without rewriting glue. It is a poor fit for teams that want a hosted control plane, a visual graph editor, or a large catalogue of pre-built integrations. The README markets simplicity, not operational maturity.

How the CodeAgent mechanism actually differs from JSON tool calls

The README's central claim is "First-class support for Code Agents," defined as an agent that "writes its actions in code (as opposed to 'agents being used to write code')." The distinction matters. In a JSON tool-calling loop, each step is one tool invocation with typed arguments. In a code-writing loop, one step can be a short program: a loop over search results, a conditional, a transformation of an intermediate value. Fewer round trips to the model is the implied benefit.

The cost is the obvious one. Generated Python runs somewhere. The README states that to make this secure, execution is supported in sandboxed environments via Blaxel, E2B, Modal, or Docker. Those are optional dependencies in pyproject.toml, not defaults: docker, e2b, modal and blaxel are separate extras. Installing the base package does not give you a sandbox. The examples directory contains examples/sandboxed_execution.py, which is where the repository points at this concern.

Model access is deliberately open. The README lists InferenceClientModel for Hugging Face inference providers, LiteLLMModel for "100+ LLMs," OpenAIModel with an api_base for OpenAI-compatible servers such as Together AI and OpenRouter, TransformersModel for local transformers models, plus AzureOpenAIModel and AmazonBedrockModel. Tools are equally open: MCP servers, LangChain tools, and a Hub Space used as a tool are all documented paths.

Installing smolagents and running a first agent

The README's quick demo installs the package with a default set of tools. The toolkit extra pulls in the search and page-fetching tools used by the example.

pip install "smolagents[toolkit]"

The package requires Python 3.10 or newer according to pyproject.toml, and its base dependencies are huggingface-hub, requests, rich, jinja2, pillow and python-dotenv. After installation, the README defines an agent with a web search tool and a default inference model, then runs a question that needs a lookup and an arithmetic step.

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel()
agent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

With stream_outputs=True the run prints steps as they happen, so you should see the agent's generated code and its observations before the final answer. If you want a different backend, the README shows swapping the model object only. For a local transformers model it gives this form, with max_new_tokens and device_map as constructor arguments.

from smolagents import TransformersModel

model = TransformersModel(
    model_id="Qwen/Qwen3-Next-80B-A3B-Thinking",
    max_new_tokens=4096,
    device_map="auto"
)

Agents can also be published. The README shows agent.push_to_hub("m-ric/my_agent") to push an agent as a Space repository, with agent.from_hub("m-ric/my_agent") to load one back.

The sandbox question the README leaves to you

This is the limitation worth weighing before anything else. An agent that writes code is an agent that executes code, and the README's own wording is that sandboxing is supported "to make this secure." Supported, not enabled. The extras list confirms it: docker, e2b, modal and blaxel each have their own dependency group, and none is part of the default install.

That is a deployment decision, and the library hands it to you rather than making it for you. The security guide distinguishes sandboxing generated snippets from isolating the entire agent: tools and model calls may still run outside the sandbox, and state may be sent to a remote executor. Restrict tool permissions, secrets and network access, and select the isolation boundary for the threat model.

A second, quieter limitation: the README leans on optional extras for nearly everything beyond the core loop. Search needs toolkit, MCP needs mcp, Gradio UI needs gradio, telemetry needs telemetry. A minimal install is genuinely minimal, and you will spend time matching extras to intent.

smolagents compared with LangChain and LangGraph style orchestration

Compared with LangChain and LangGraph, the architectural difference is real rather than cosmetic. LangChain and LangGraph are orchestration frameworks: you compose chains or nodes into a graph, and the framework owns the control flow. smolagents puts the control flow inside the model's generated Python. The agent decides to loop, branch or call a tool by writing the loop, the branch or the call.

That changes where complexity lives. In a graph framework, the topology is inspectable before the run, and each node is a unit you can test. In smolagents, the topology emerges per step, and the artifact you inspect is generated code. The README's answer to that is scale: roughly 1,000 lines of agent logic, which a single engineer can read in an afternoon. Whether that is a better trade depends on whether you would rather debug a graph or read generated Python.

Interoperability cuts the other way in smolagents' favour. The README documents pulling tools from MCP servers, from LangChain, and from a Hub Space, so adopting smolagents does not force you to abandon a LangChain tool you already have. The reverse is less clearly documented in the README.

Maintenance, licence and what an upgrade costs

The repository is not archived. Its last push was on 2026-10-29, and the most recent release listed is v1.26.0 on 2026-05-29, following v1.25.0 on 2026-05-14 and v1.24.0 on 2026-01-16. The version string in pyproject.toml is 1.27.0.dev0, so main is ahead of the last tagged release. The gap between the January and May releases, then between May and the October push, is worth noting if you pin versions: this is not a project that ships weekly.

Licensing is Apache-2.0, per the LICENSE file and the badge in the README. That is a permissive licence with an explicit patent grant, and it imposes notice and attribution obligations rather than copyleft ones. The README's own header carries the Apache boilerplate and a copyright line for The HuggingFace Team. None of this is legal advice, and if you redistribute a modified smolagents you should read the licence text rather than this summary.

The upgrade cost is dominated by extras, not by the core API. Because model backends, sandboxes, MCP support and telemetry all live in separate dependency groups with their own version floors (for example litellm>=1.60.2, docker>=7.1.0, mcpadapt>=0.1.13), a breaking change upstream in any one of them surfaces as an install failure in that extra rather than in smolagents itself. Pinning the extras you actually use is cheaper than pinning the whole all group.

Editorial conclusion

Adopt smolagents if you want a small, readable agent loop in Python and you are willing to decide how untrusted generated code executes. Skip it if you need a batteries-included orchestration platform or if you cannot run a sandbox. Before committing, verify which optional extra matches your model provider, and confirm that your chosen execution backend (Docker, E2B, Modal or Blaxel) is one your infrastructure already permits.

Frequently asked questions

Official sources

1. huggingface/smolagents on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases