smolagents: Hugging Face's Minimal Code-Agent Library

What it is: smolagents is Hugging Face's deliberately tiny agent library — the core logic is on the order of a thousand lines of code — whose signature idea is the CodeAgent: instead of emitting JSON tool calls, the agent writes and executes Python snippets to act, which makes it unusually well suited to data analysis.

Why does writing Python beat JSON tool calls for data work?

A JSON-tool-call agent needs one round trip per action: call a tool, read the result, call the next. A CodeAgent composes several actions in one snippet — loop, branch, chain intermediate variables — exactly how a human analyst works in a notebook. Hugging Face's own benchmarks report fewer steps and better accuracy on multi-step tasks; for pandas-style analysis, code is simply the native language of the job.

pip install smolagents

from smolagents import CodeAgent, InferenceClientModel

model = InferenceClientModel()  # or LiteLLMModel("claude-...", ...) etc.
agent = CodeAgent(
    tools=[],
    model=model,
    additional_authorized_imports=["pandas", "numpy"],
)
agent.run("Load sales.csv, then report average order value by month.")

The agent responds with Python (e.g. pd.read_csv(...), a groupby, a final answer), smolagents executes it, and any traceback goes back to the model for self-correction.

How does smolagents sandbox generated code?

Running LLM-written Python is the obvious risk, so smolagents ships several execution modes: a restricted local Python executor (limited imports and builtins — you must whitelist pandas via additional_authorized_imports), plus stronger isolation through E2B cloud sandboxes, Docker containers, or a WebAssembly runtime. The local executor is fine for trusted, personal analysis; use Docker or E2B for anything exposed to other people's inputs.

Which models can smolagents use?

It's model-agnostic by design. First-class classes cover Hugging Face Inference Providers, local Transformers models, and — via LiteLLM or OpenAI-compatible clients — OpenAI, Anthropic, Gemini, Ollama, and most other endpoints. Because the framework asks the model to write code rather than follow a proprietary tool-call format, strong open-weights code models work well, making fully local, zero-API-cost data agents realistic.

How do you give a smolagents agent custom tools?

Wrap any Python function with the @tool decorator — a docstring and type hints become the tool's description — and pass it into the agent. Because the agent writes code, it can call your tool inside loops and combine it with pandas in the same snippet, something JSON-tool agents can't do in one step. The library also ships built-ins like web search, and tools can be shared or pulled from the Hugging Face Hub.

When does minimal beat a heavyweight framework?

Choose smolagents when you want one agent that solves a task by writing code, and you want to be able to read the entire framework source in an afternoon. Fewer abstractions means less magic to debug when prompts go sideways. Reach for CrewAI or LangGraph instead when you need multi-agent orchestration, durable state and checkpoints, or complex human-in-the-loop workflows — smolagents deliberately doesn't try to be that. Many data teams find a single CodeAgent covers 80% of what they imagined needing a crew for.

Author & links

Author: Hugging Face

Repo: github.com/huggingface/smolagents

License: Apache-2.0

Related skills

For typed outputs and structured validation see Pydantic-AI; for role-based multi-agent teams see CrewAI.

← Back to Agent Frameworks