SmolAgents

Overview

SmolAgents is a lightweight, code-based AI agent framework created by Hugging Face. Unlike traditional agent frameworks that use complex abstractions, SmolAgents takes a radically simple approach: agents think in code. With approximately 1,000 lines of code, it prioritizes transparency, simplicity, and observability over feature complexity.

The core philosophy is that agents should execute Python code to perform actions, making the entire reasoning process fully observable and debuggable. This contrasts with frameworks that use black-box action selection, where the agent's decision-making process is opaque.

Built by the Hugging Face team, SmolAgents integrates seamlessly with the Hub ecosystem, allowing easy access to models, tools, and datasets. It's designed for developers who want to understand exactly what their agents are doing, making it ideal for education, prototyping, and production scenarios where transparency matters.

Features

• Code-based Action Execution: Agents write and execute Python code to perform actions, making reasoning fully transparent
• ~1,000 Lines of Code: Minimal codebase for maximum simplicity and understandability
• Hugging Face Hub Integration: Native support for models, tools, and datasets from the Hub
• Flexible Model Support: Works with any Hugging Face model or external API
• Sandboxed Execution: Safe code execution with configurable sandboxing
• Tool Framework: Easy-to-create custom tools with simple decorators
• Multi-Modal Support: Handle text, images, and other modalities

Installation

pip install smolagents[toolkit]

The [toolkit] extra includes additional tools like web browsing, code interpretation, and more.

Quick Start

from smolagents import CodeAgent, HfApiModel

# Create a simple agent
model = HfApiModel(model_id="Qwen/Qwen2.5-72B-Instruct")
agent = CodeAgent(tools=[], model=model)

# Run a task
result = agent.run("What is the capital of France?")
print(result)

Creating Custom Tools

from smolagents import tool

@tool
def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    # Your implementation here
    return f"The weather in {location} is sunny, 25°C"

agent = CodeAgent(tools=[get_weather], model=model)
agent.run("What's the weather like in Paris?")

Core Concepts

Code Agent

The CodeAgent is the main agent class. It generates Python code to solve tasks, then executes that code in a sandboxed environment. The agent iteratively:

1. Receives a task and conversation history
2. Generates Python code to solve the task
3. Executes the code and observes results
4. Iterates until the task is complete

Tools

Tools are simple Python functions decorated with @tool. Each tool has a name, description, and input schema. The agent can call tools by generating code that invokes them.

Models

SmolAgents supports any model that can be accessed through the Hugging Face Hub or external APIs. The HfApiModel class provides a unified interface for model inference.

Advanced Features

Multi-Agent Systems

from smolagents import CodeAgent, HfApiModel

model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")

researcher = CodeAgent(
    tools=[web_search_tool],
    model=model,
    name="researcher",
    description="Researches topics and gathers information"
)

writer = CodeAgent(
    tools=[],
    model=model,
    name="writer",
    description="Writes articles based on research"
)

# Agents can work together
research_result = researcher.run("Research the latest developments in AI agents")
article = writer.run(f"Write an article about: {research_result}")

Web Agent

The WebAgent is a pre-built agent for web browsing tasks:

from smolagents import web_agent

result = web_agent.run("Find the latest news about AI agents and summarize the top 3 stories")

Code Interpreter

Built-in code interpreter for data analysis, visualization, and computation:

from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[code_interpreter_tool],
    model=model
)
agent.run("Analyze this CSV file and create a chart showing sales trends")

Examples

Trip Planning

agent.run("""
Plan a 5-day trip to Japan including:
1. Flight options from New York
2. Hotel recommendations in Tokyo
3. Daily itinerary with attractions
4. Budget estimate
""")

Data Analysis

agent.run("""
Load the sales_data.csv file, calculate monthly revenue, 
and create a visualization showing trends over the past year.
""")

Research Report

agent.run("""
Research the history and current state of large language models.
Write a comprehensive report with citations.
""")

Pros

• ✅ Extremely Lightweight: ~1,000 lines of code, easy to understand and modify
• ✅ Full Transparency: Code-based reasoning is fully observable and debuggable
• ✅ Hugging Face Integration: Seamless access to models, tools, and datasets
• ✅ Educational Value: Perfect for learning how agents work internally
• ✅ No Complex Abstractions: Simple API that's easy to learn
• ✅ Sandboxed Execution: Safe code execution with configurable security

Cons

• ❌ Python Only: No TypeScript or other language support
• ❌ Less Production-Ready: Fewer production features than full frameworks
• ❌ Smaller Community: Less community support and fewer pre-built tools
• ❌ Manual Setup: More manual configuration for complex tasks
• ❌ Limited Ecosystem: Fewer integrations compared to LangChain/CrewAI

Use Cases

Use Case	Why SmolAgents
Education & Learning	Understand agent internals with full transparency
Rapid Prototyping	Quick agent setup with minimal boilerplate
Data Analysis	Code-based reasoning for data tasks
Research	Transparent, reproducible agent experiments
Hugging Face Projects	Native integration with Hub models and tools

Comparison with Alternatives

Feature	SmolAgents	LangChain	CrewAI	Hugging Face Agents
Paradigm	Code-based	Chain-based	Role-based	Various
Transparency	✅ Full	⚠️ Partial	⚠️ Partial	Varies
Lines of Code	~1,000	100,000+	10,000+	Varies
Hugging Face Native	✅ Yes	⚠️ Via integrations	❌ No	✅ Yes
TypeScript Support	❌ No	✅ Yes	❌ No	❌ No
Learning Curve	Low	High	Low	Low-Medium
Best for	Education, transparency	Complex apps	Multi-agent teams	HF ecosystem

Best Practices

1. Start with simple agents — Build up complexity gradually
2. Use CodeAgent for most tasks — Leverage code-based reasoning
3. Create reusable tools — Define tools once, use across agents
4. Test in sandbox first — Verify code execution safety
5. Use WebAgent for browsing — Pre-built for web tasks
6. Document your agents — Code-based approach makes documentation easier

Troubleshooting

Issue	Solution
Code execution fails	Check sandbox permissions and dependencies
Model not responding	Verify Hugging Face token and model access
Tool not found	Ensure tool is registered with the agent
Memory issues	Reduce context size or use smaller models
Slow execution	Use faster models for simple tasks

Resources

• Official Documentation
• GitHub Repository
• Hugging Face Hub
• Examples Gallery