smolagents

By Hugging Face

Hugging Face's minimal library for agents that act by writing and running code

Website ↗ Repository ↗ Docs ↗

v1.26.02026-05-29PythonApache-2.0

#code-agents #huggingface #litellm #python

28.5k Completely free Open source

Doc version 1.0 · Updated June 28, 2026

Related tools

LiteLLM

Gateways & Routers

CrewAI

Multi-Agent Orchestration

Overview

smolagents is a deliberately tiny library from Hugging Face — the agent logic fits in roughly a thousand lines — built around code agents that take actions by writing and running Python.
It is model-agnostic: local transformers, Hugging Face Hub models, or any provider through LiteLLM.

flowchart LR
  task[task] --> agent[CodeAgent]
  agent --> code[writes Python]
  code --> run[executes]
  run --> agent
  agent --> out[answer]

The Code samples tab shows a code agent backed by LiteLLM.

When to use it

Reach for smolagents when you want a minimal, hackable agent loop, or when code-writing actions suit the task (math, data wrangling, multi-step tool use) better than JSON function calls.

Example

Python · code agent

When to use

Pick smolagents when you want agents that write code to act rather than emit JSON tool calls — often fewer steps for computational tasks.

How it flows

The CodeAgent writes Python, runs it in a sandbox, observes the result, and iterates until it answers.

Structure

flowchart LR
  task[task] --> agent[CodeAgent]
  agent --> code[writes Python]
  code --> run[executes]
  run --> agent
  agent --> out[answer]

from smolagents import CodeAgent, LiteLLMModel

# Code agents act by writing and running Python; LiteLLM routes to any provider.
model = LiteLLMModel(model_id="anthropic/claude-opus-4-8")
agent = CodeAgent(tools=[], model=model)
print(agent.run("Compute 2 ** 10 + 5 in Python and return the number."))

Example

smolagents — implementation sample

A real, runnable mini-project. Download it and run with Docker.

View samples/smolagents_1 on GitHub ↗

June 28, 2026

smolagents — implementation sample

A tiny smolagents sample: it runs a code agent that writes and executes Python to solve the task. The model is routed through LiteLLM, so any provider works via MODEL.

Configure

cd samples/smolagents_1
cp .env.sample .env
# edit .env: set ANTHROPIC_API_KEY (or swap MODEL + the matching key)

Run with Docker

cd samples/smolagents_1
docker build -t aas-smolagents .
docker run --rm --env-file .env aas-smolagents "Compute 2 ** 10 + 5 in Python and return the number."

Run with Docker (in a devcontainer with DooD)

The foreground docker run may print nothing under Docker-outside-of-Docker — run detached and follow the logs:

docker logs -f "$(docker run -d --env-file .env aas-smolagents "Compute 2 ** 10 + 5 in Python and return the number.")"

Run locally

cd samples/smolagents_1
pip install -r requirements.txt
python app.py "Compute 2 ** 10 + 5 in Python and return the number."

Example run

The agent prints its reasoning steps; the final line is the answer. Wording varies, but the computed value is stable. One run with claude-opus-4-8:

result: 1029

Files

.env.sample

# Copy to `.env` and add your Anthropic API key (or swap MODEL for another
# provider that LiteLLM supports, with the matching key).
#   cp .env.sample .env
ANTHROPIC_API_KEY=

MODEL=anthropic/claude-opus-4-8

app.py

"""smolagents: a code agent that acts by writing and running Python.

The agent writes Python to solve the task, runs it, and returns the result.
Model is routed through LiteLLM, so any provider works via MODEL.

Run:
    docker build -t aas-smolagents .
    docker run --rm --env-file .env aas-smolagents "Compute 2 ** 10 + 5."
"""

import os
import sys

from dotenv import load_dotenv
from smolagents import CodeAgent, LiteLLMModel

load_dotenv()

MODEL = os.environ.get("MODEL", "anthropic/claude-opus-4-8")


def main() -> None:
    task = " ".join(sys.argv[1:]) or "Compute 2 ** 10 + 5 in Python and return the number."
    agent = CodeAgent(tools=[], model=LiteLLMModel(model_id=MODEL))
    print("result:", agent.run(task))


if __name__ == "__main__":
    main()

Dockerfile

FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

ENTRYPOINT ["python", "app.py"]