Unpacking SmolAgents: A Beginner-Friendly Guide to Agentic Systems

AI is evolving beyond simple responses. Agents don’t just answer questions—they take action, adapt, and collaborate. With SmolAgents, building these intelligent systems is easier than ever. Let's dive in.

Imagine a world where your AI-powered applications don’t just answer questions but take actions, solve problems step-by-step, and even collaborate with other AI systems to get things done. That’s the magic of agents in AI. Agents are more than just passive assistants—they're dynamic, decision-making systems that can think, act, and learn.

But wait, isn’t this what Large Language Models (LLMs) already do? Yes and no. While LLMs generate responses, agents use LLMs as their "brains" to execute workflows, make decisions, and interact with tools.

In this post we provide an introduction to SmolAgents—a lightweight, intuitive library that makes building powerful agents. Whether you’re a beginner or an AI pro, this guide will take you from zero to hero in understanding and building agents using SmolAgents.

1. What Are Agents?

At their core, agents are systems that use LLMs to decide and execute workflows. They bring agency to AI, meaning they can dynamically decide how to achieve a task instead of following a fixed, pre-programmed path.

Levels of Agency

Agents exist on a spectrum of complexity:

  1. Simple Processors: LLM outputs don’t affect the program's flow.
  2. Routers: The LLM output determines a specific path (e.g., if/else logic).
  3. Tool Callers: The LLM decides which tool to use for specific actions.
  4. Multi-Step Agents: Agents iterate through multiple steps, adjusting based on observations.
  5. Multi-Agent Systems: Multiple agents collaborate, each specializing in specific tasks.

SmolAgents shine in implementing multi-step agents and multi-agent systems, making it easy to leverage complex workflows with minimal setup.

2. Why SmolAgents?

SmolAgents stands out for three reasons:

  1. Simplicity: A minimalistic design (~1,000 lines of code) means less overhead and more flexibility.
  2. Versatility: Supports LLMs from OpenAI, Hugging Face, Anthropic, and others.
  3. Code-First Approach: Instead of JSON-based actions, agents in SmolAgents write and execute Python code—more powerful and natural for complex tasks.

3. Building Your First Agent

Let’s start with a simple example: a CodeAgent that calculates the 118th Fibonacci number. Follow these steps:

Step 1: Install SmolAgents

pip install smolagents transformers huggingface_hub

Step 2: Initialize Your Agent

SmolAgents requires two key components:

  1. Model: The LLM powering your agent.
  2. Tools: Functions the agent can call to perform tasks.

Here’s how to initialize a CodeAgent:

from smolagents import CodeAgent, HfApiModel

# Set up the LLM model (Hugging Face API in this case)
model_id = "meta-llama/Llama-3.3-70B-Instruct"
model = HfApiModel(model_id=model_id, token="<YOUR_HUGGINGFACEHUB_API_TOKEN>")

# Initialize the agent with default tools
agent = CodeAgent(tools=[], model=model, add_base_tools=True)

# Run a simple task
result = agent.run("Could you calculate the 118th Fibonacci number?")
print(result)

Step 3: Observing the Agent’s Thought Process

SmolAgents log each step of an agent’s reasoning and execution. After the run:

# Inspect detailed logs
print(agent.logs)

# Generate a summary for review
agent.write_inner_memory_from_logs()

4. Core Features of SmolAgents

A. Code Execution

Unlike traditional agents that generate JSON-like tool calls, SmolAgents use Python code. This makes:

  • Composability: Easily nest actions or reuse functions.
  • Debugging: Leverage Python’s error handling and logging.
  • Familiarity: Python is already the lingua franca of programming.

Here’s an example of a CodeAgent fetching the title of a webpage:


agent.run("Could you get me the title of the page at 'https://huggingface.co/blog'?")

B. Secure Code Execution

SmolAgents ensure safety by:

  • Restricting imports to a predefined list.
  • Preventing unsafe operations (e.g., infinite loops).
  • Offering remote execution via E2B for added security.

C. Tool Integration

Tools are predefined functions that agents use to perform actions. For example:

from smolagents import DuckDuckGoSearchTool

search_tool = DuckDuckGoSearchTool()
print(search_tool("Who's the president of the United States?"))

5. Advanced Example: Weather Bot

Let’s build an agent that retrieves weather data based on user input.

Step 1: Define a Custom Tool

from smolagents import tool
import datetime

@tool
def get_weather_api(location: str, date_time: str) -> str:
    """
    Retrieves weather data for a given location and date.

    Args:
        location: City and country (e.g., "Paris, France").
        date_time: Date in '%Y-%m-%d' format.
    """
    # Mock API call
    return f"Weather in {location} on {date_time}: Sunny, 25°C."

Step 2: Integrate the Tool with CodeAgent

agent = CodeAgent(tools=[get_weather_api], model=model)
result = agent.run("What's the weather in Tokyo on 2025-01-10?")
print(result)

Step 3: Observing Execution

Agents break tasks into steps:

  1. Think about the task.
  2. Use tools (e.g., call get_weather_api).
  3. Return the final result.

6. Taking It Further: Multi-Agent Systems

Scenario: Planning a Surf Trip

A user wants to plan a surf trip. The task involves:

  • Checking weather conditions.
  • Calculating travel distances.
  • Checking availability of surf instructors.

Step 1: Define Specialized Agents

from smolagents import ManagedAgent

# Weather agent
weather_agent = CodeAgent(tools=[get_weather_api], model=model)
managed_weather_agent = ManagedAgent(
    agent=weather_agent, name="weather", description="Fetches weather data."
)

# Manager agent
manager_agent = CodeAgent(
    tools=[], model=model, managed_agents=[managed_weather_agent]
)

Step 2: Run the Manager Agent

result = manager_agent.run("Plan a surf trip in Bali next week.")
print(result)

Here, the manager delegates tasks to specialized agents, mimicking real-world teamwork.

7. Debugging and Best Practices

Common Pitfalls

  • LLM Missteps: Use stronger models or guide them with clearer prompts.
  • Tool Overload: Too many tools can confuse the agent. Use only what’s necessary.
  • Security Risks: Use E2B for untrusted environments.

Best Practices

  1. Simplify workflows—group related actions into single tools.
  2. Log everything for better debugging.
  3. Always validate user inputs to prevent tool misuse.

8. Conclusion: From Basics to Advanced Mastery

SmolAgents democratize the power of agentic systems, making them accessible for everyone—from hobbyists to professionals. Whether you’re solving simple tasks or orchestrating complex multi-agent workflows, SmolAgents’ code-first approach ensures both flexibility and power.

Now it’s your turn to build agents that think, act, and collaborate. Dive in, experiment, and redefine what’s possible with AI. If you need to go deeper, you can find more information here.

Until the next one,

‍

Cohorte Team

February 12, 2025