Smolagents: Lightweight AI Agent Framework by HuggingFace

Introduction

Smolagents is a lightweight and minimalist AI agent framework from HuggingFace, designed for building AI agents with a code-first approach. Unlike other agent frameworks that tend to be complex and heavy, Smolagents focuses on simplicity while still providing powerful features such as multi-step reasoning, custom tool creation, and multi-agent orchestration.

This framework is ideal for developers who want to build AI agents without excessive overhead. Smolagents uses a unique approach where the agent generates Python code as its "actions" instead of rigid JSON formats, making agents more flexible and expressive.

In this tutorial, we will learn how to use Smolagents from installation, understanding agent types, creating custom tools, to building a research agent that can search the web, process data, and generate reports.

Prerequisites

Before getting started, make sure you have:

• Python 3.10 or later
• pip package manager
• API key from HuggingFace, OpenAI, or Anthropic
• Basic understanding of Python and AI/LLM concepts

Installation

Basic Installation

# Install smolagents
pip install smolagents

Install with additional dependencies for all features
pip install smolagents[all]

Or install specific dependencies
pip install smolagents[openai]      # For OpenAI
pip install smolagents[anthropic]   # For Anthropic
pip install smolagents[gradio]      # For Gradio UI
pip install smolagents[telemetry]   # For monitoring

Verify Installation

import smolagents
print(f"Smolagents version: {smolagents.version}")

Test basic import
from smolagents import CodeAgent, HfApiModel
print("Import successful!")

Setup Environment Variables

# For HuggingFace
export HFTOKEN="hfyourtokenhere"

For OpenAI
export OPENAIAPIKEY="sk-your-key-here"

For Anthropic
export ANTHROPICAPIKEY="sk-ant-your-key-here"

CodeAgent vs ToolCallingAgent

Smolagents provides two main agent types that take different approaches to completing tasks.

CodeAgent

CodeAgent generates and executes Python code as its actions. This is the recommended agent type because it is more flexible and efficient.

from smolagents import CodeAgent, HfApiModel

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


Create CodeAgent
agent = CodeAgent(
    tools=[],  # No additional tools
    model=model,
    maxsteps=5
)

Run agent
result = agent.run("Calculate the average of the following numbers: 15, 28, 42, 37, 56")
print(result)

Advantages of CodeAgent:

• Generates Python code that can perform complex computations
• More efficient as it can combine multiple operations in a single step
• Supports variables and logic flow
• Output is easier to debug

ToolCallingAgent

ToolCallingAgent uses the standard tool calling format (similar to function calling in OpenAI). This agent calls tools one by one in JSON format.

from smolagents import ToolCallingAgent, HfApiModel

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


Create ToolCallingAgent
agent = ToolCallingAgent(
    tools=[],
    model=model,
    maxsteps=5
)

Run agent
result = agent.run("What is the result of 25  48?")

print(result)

from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool

Initialize search tool
searchtool = DuckDuckGoSearchTool()


Create agent with search tool
agent = CodeAgent(
    tools=[searchtool],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

    maxsteps=5