SmoLAGents: Your Tiny Yet Mighty AI Agents 🤖

Ever felt overwhelmed by complex AI frameworks? Enter SmoLAGents – the minimalist's answer to building powerful AI agents. With just ~1000 lines of code, it's like the Marie Kondo of agent frameworks – keeping only what sparks joy (and functionality)!

What is SmoLAGents?

At its core, SmoLAGents is a Python library that lets you create AI agents without the bloat. Think of it as a LEGO set for AI – you get the essential building blocks to construct agents that can perform tasks, make decisions, and even write code.

Why "smol"?

The "smol" in SmoLAGents isn't just cute internet speak – it's a philosophy. In a world where AI frameworks often feel like trying to swallow an elephant, SmoLAGents takes the "small is beautiful" approach:

• Minimal abstractions: No maze of complex hierarchies
• Readable codebase: ~1000 lines that you can actually understand
• Zero unnecessary dependencies: Just what you need, nothing more

Key Features 🚀

1. Universal LLM Support Want to use GPT-4? Llama? That cool new model you just found? SmoLAGents plays nice with them all, supporting models from OpenAI, Anthropic, and any model hosted on Hugging Face Hub.
2. Code-First Approach Unlike other frameworks that treat code generation as an afterthought, SmoLAGents makes it a first-class citizen. Your agents can write, execute, and debug code as naturally as breathing.
3. Hugging Face Integration Share and load tools directly from the Hub, because good agents deserve good tools. It's like an App Store for agent capabilities!
4. Safety First Runs code in a secure environment by default, because nobody likes unexpected rm -rf / surprises. You control what your agents can access.

The best part? You don't need a Ph.D. in AI to use it. If you can write Python and have a curious mind, you're already qualified to start building with SmoLAGents. Ready to make your AI agents work smarter, not harder? Let's dive in! 🏊‍♂️

Getting Started with SmoLAGents 🚀

Installation

pip install smolagents

Basic Setup

To create your first agent, you'll need:

1. Model Selection: Choose your LLM backend

from smolagents import HfApiModel

# Use Hugging Face model
model = HfApiModel(model_id="meta-llama/Llama-3.3-70B-Instruct")

# For gated models, add your token
model = HfApiModel(
    model_id="meta-llama/Llama-3.3-70B-Instruct",
    token="YOUR_HF_TOKEN"
)

2. Tools Selection: Pick your agent's capabilities

from smolagents import DuckDuckGoSearchTool

# Single tool
tools = [DuckDuckGoSearchTool()]

# Or use base toolbox
tools = []  # Empty list + base tools

Creating Your First Agent

Here's a complete example that creates a web-searching agent:

from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiModel

# Initialize agent with search capability
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=HfApiModel(),
    add_base_tools=True  # Adds default toolbox
)

# Run your first task
response = agent.run(
    "What's the fastest land animal and how quickly can it run?"
)

Security Note 🔒

By default, CodeAgent runs in a secure local environment. For additional safety:

• Use use_e2b_executor=True for sandboxed execution
• Control imports with additional_authorized_imports=['requests', 'pandas']

Your agent is now ready to tackle tasks! Want to see it in action? Try the Gradio interface:

from smolagents import GradioUI

GradioUI(agent).launch()

Understanding Agentic Systems in SmoLAGents

Core Concepts

AI Agents are programs where LLM outputs control the workflow. Agency operates on a spectrum:

1. Simple Processor (☆☆☆): LLM output → direct processing
2. Router (★☆☆): LLM output → conditional branching
3. Tool Caller (★★☆): LLM output → function execution
4. Multi-step Agent (★★★): LLM output → iterative execution loop
5. Multi-Agent (★★★): LLM output → triggers other agents

Agent Architecture

SmoLAGents implements two key architectures:

1. CodeAgent

while not task_complete:
    code = llm.generate_code(memory)
    result = execute_code(code)
    memory.append(result)

1. ToolCallingAgent

while not task_complete:
    action = llm.generate_action_json(memory)
    result = execute_tool(action)
    memory.append(result)

Components and Roles

1. LLM Engine: Generates responses and decisions
2. Tools: External functions the agent can access
3. Parser: Extracts executable actions from LLM output
4. Memory: Stores conversation and execution history
5. Error Handler: Manages failures and retries

Framework Comparison

SmoLAGents vs Others:

• Code-First: Uses Python code instead of JSON for actions
• Minimalist: ~1000 lines core codebase
• Flexible: Supports both code and tool-calling agents
• Secure: Built-in sandboxed execution options

When to use agents:

• ✅ Complex, unpredictable workflows
• ✅ Tasks requiring multiple steps/tools
• ⛔ Simple, deterministic processes
• ⛔ Tasks with fixed decision trees

Self-corrective Text to SQL Example

Implementation

from smolagents import CodeAgent, HfApiModel, tool

@tool
def sql_engine(query: str) -> str:
    """Execute SQL queries and return results as string"""
    with engine.connect() as con:
        rows = con.execute(text(query))
        return "\\n".join(str(row) for row in rows)

agent = CodeAgent(
    tools=[sql_engine],
    model=HfApiModel("Qwen/Qwen2.5-Coder-32B-Instruct")
)

Error Handling

1. Query Validation

try:
    # Validate SQL syntax
    parsed_sql = sqlparse.parse(query)[0]
    if not valid_syntax(parsed_sql):
        raise SQLSyntaxError

    # Execute query
    result = sql_engine(query)

except SQLError as e:
    # Agent generates corrected query
    corrected_query = agent.correct_sql(query, e)

1. Result Verification

def verify_results(query_result):
    if not query_result.strip():
        return "No results found. Query might need refinement."
    try:
        parsed = json.loads(query_result)
        validate_schema(parsed)
    except:
        return "Invalid result format"

Performance Optimization

1. Query Planning

• Use EXPLAIN for query analysis
• Add appropriate indexes
• Optimize JOIN operations

1. Caching

from functools import lru_cache

@lru_cache(maxsize=100)
def cached_sql_query(query_hash):
    return sql_engine(query)

Additional Use Cases

1. Data Analysis

• Time series analysis
• Aggregation queries
• Statistical computations

1. Task Automation

• Report generation
• Data validation
• ETL processes

1. Code Generation

• SQL schema creation
• Stored procedures
• Database migrations

Multi-Agent Web Browser Example

Architecture

# Initialize model
model = HfApiModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct")

# Web search agent with tools
web_agent = ToolCallingAgent(
    tools=[DuckDuckGoSearchTool(), visit_webpage],
    model=model,
    max_steps=10
)

# Wrap in managed agent
managed_web_agent = ManagedAgent(
    agent=web_agent,
    name="search",
    description="Runs web searches for you."
)

# Manager agent
manager_agent = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[managed_web_agent],
    additional_authorized_imports=["time", "numpy", "pandas"]
)

Key Components

1. Web Search Agent

• DuckDuckGo search tool
• Webpage visit tool
• JSON tool calling format
• 10-step limit for exploration

1. Manager Agent

• Orchestrates web searches
• Processes results
• Performs calculations
• Code execution capability

Example Task

# Complex research question
query = """
If LLM trainings continue to scale up at the current rhythm
until 2030, what would be the electric power in GW required?
"""

result = manager_agent.run(query)

Performance Features

1. Parallel Processing

• Manager delegates searches
• Web agent explores multiple pages
• Results aggregated efficiently

1. Error Recovery

• Failed searches retried
• Alternative sources explored
• Data validation checks

1. Resource Management

• Step limits prevent infinite loops
• Memory efficient web content parsing
• Focused search strategies

1. Extensibility

• Add specialized agents
• Custom tool integration
• Flexible task distribution