Open SourcePython

Smolagents

by Hugging FaceUpdated Jun 15, 2025

Ultra-minimal agent framework from Hugging Face where agents write and execute Python code to achieve goals. Instead of traditional tool calling via JSON, smolagents uses a 'code agent' approach where the LLM generates Python code snippets that are executed in a sandboxed environment. This leads to more flexible and composable agent behavior.

Architecture Overview

Smolagents provides two agent types: CodeAgent (generates and executes Python code) and ToolCallingAgent (uses standard tool calling). Both run in a ReAct-style loop where the model reasons about the task, takes an action (code or tool call), observes the result, and repeats. Tools are simple Python functions or classes. The framework includes a secure sandboxed execution environment and supports any model via a lightweight model adapter interface.

When to Use Smolagents

Learning and understanding agent fundamentals
Code-generation and data analysis tasks
Rapid prototyping of agent ideas
Hugging Face model and dataset interactions
Research experiments with minimal overhead

Strengths & Weaknesses

Strengths

Extremely simple API (< 1000 lines of core code)
Code-first approach enables flexible tool composition
Great for learning agent concepts hands-on
Hugging Face Hub integration for models and tools
Sandboxed code execution for safety

Weaknesses

Limited production features (no persistence, limited memory)
Basic orchestration — not suitable for complex multi-agent systems
Code execution approach may not suit all use cases

Quick Start

python

from smolagents import CodeAgent, tool, HfApiModel

@tool
def get_weather(city: str) -> str:
    """Get the current weather for a given city.

    Args:
        city: The city name to get weather for.
    """
    return f"Sunny, 22°C in {city}"

# Use any Hugging Face model or OpenAI
model = HfApiModel("Qwen/Qwen2.5-Coder-32B-Instruct")

agent = CodeAgent(
    tools=[get_weather],
    model=model,
)

result = agent.run("What's the weather in London?")
print(result)

Features at a Glance

Developer	Hugging Face
Language	Python
License	Apache-2.0
GitHub Stars	15k+
MCP Support	No
Multi-Agent	Yes

Notable Users

Hugging FaceCERNAllen AIBigScience

Resources

Official Documentation

https://huggingface.co/docs/smolagents/

GitHub Repository

https://github.com/huggingface/smolagents

Explore Related Content

Concept

Edit on GitHub