Building AI agents is a complex process. But, smolagents helps us build lightweight, flexible AI agents. It’s a minimal Python framework that makes creating AI agents surprisingly simple. In this blog, we’ll walk through the basics of building agents with smolagents.

Why smolagents?

smolagents is:

• Lightweight and minimal
• Flexible with LLM providers (OpenAI, Azure, Hugging Face, etc.)
• Code-first (Python all the way)
• Quick to experiment with

It’s perfect when your application logic is straightforward and you want to build and test quickly.

How smolagents Agents Work

Agents in smolagents operate as multi-step agents. Each step consists of two parts:

1. A thought – what action the agent decides to do next
2. A tool call and execution – performing that action

The agent thinks, acts, observes the result, and repeats this process until the task is complete.

Code Agents

The most common type of agent in smolagents is the Code Agent.

These agents generate Python code snippets as actions. This has some major advantages over traditional JSON-based formats:

• Code is naturally composable
• It manages objects and state easily
• It’s general and expressive
• LLMs tend to reason better with code

Code Agent Workflow (CodeAgent.run())

Here’s how the agent operates under the hood:

1. System prompt is stored in a SystemPromptStep.

2. User query is logged as a TaskStep.

3. Then a loop starts:

   • agent.write_memory_to_messages() converts logs into chat-style messages.
   • These messages go to the model.
   • The model replies with a Python code snippet (an action).
   • The action is executed.
   • Result is saved in an ActionStep.

4. If there are any callbacks (like agent.step_callback), they’re triggered at the end of each step.

This continues until the task is done or a stopping condition is met.

Tool-Calling Agents

While Code Agents use Python snippets, Tool-Calling Agents use JSON objects to call tools.

These are useful if you want to rely on LLM providers’ built-in function/tool-calling systems (like OpenAI’s functions or tools feature).

They follow the same multi-step logic as Code Agents—the only difference is in how they define and execute actions.

Defining Tools for Your Agent

Whether you’re using Code Agents or Tool-Calling Agents, your agent will need tools to interact with the environment—like searching the web, processing data, or generating answers.

There are two main ways to define tools:

1. The @tool Decorator (For Simple Tools)

The simplest way to create a tool is by decorating a Python function.

from smolagent.tools import tool

@tool
def greet(name: str) -> str:
    """Greets the user by name."""
    return f"Hello, {name}!"

2. Tool as a Python Class (For Complex Tools)

For more advanced use cases, you can define a tool as a class.

from smolagent.tools import Tool

class MultiplyTool(Tool):
    name = "multiply"
    description = "Multiplies two numbers"
    inputs = {"x": int, "y": int}
    output_type = int

    def forward(self, x, y):
        return x * y

This gives you more flexibility and structure, especially when tools need to maintain internal state or perform complex logic.

Example: Building a Simple Math Agent

Here’s a basic example of how you might set up a math-solving agent using smolagents:

from smolagent import CodeAgent
from smolagent.tools import tool

@tool
def add(x: int, y: int) -> int:
    """Adds two numbers."""
    return x + y

tools = [add]

agent = CodeAgent(
    name="MathAgent",
    description="Solves simple math problems.",
    tools=tools,
    model="gemma2"
)

response = agent.run("What is 15 plus 27?")
print(response)

This concludes the tutorial on how to build agents using smolagents.