HuggingFace Smolagents

Smolagents is a new library from Hugging Face that allows developers to run powerful AI agents with just a few lines of code. It is designed for simplicity while offering advanced capabilities, making it a great choice for both beginners and experienced users

Key Features of SmolAgents

✨ Simplicity

Smolagents is built with minimal abstractions, keeping the logic close to raw code. This makes it easier to understand, modify, and use without unnecessary complexity. Developers can quickly implement and run agents without dealing with excessive layers of code

🌐  Code Agents

One of the standout features of Smolagents is its support for Code Agents. These agents write their actions in code, majorly python, rather than just being tools to generate code. This makes them more flexible and efficient for various automation and AI-driven tasks.

To ensure security, SmolAgents supports execution in sandboxed environments using E2B. This allows developers to run code agents safely without risking unintended consequences on their systems

🧑‍💻 ToolCallingAgent Support

In addition to Code Agents, SmolAgents supports the standard ToolCallingAgent. This type of agent writes actions as JSON or text blobs, making it useful for structured interactions and integrations

🤗  Hugging Face Hub Integration

SmolAgents is integrated with the Hugging Face Hub, allowing users to easily share and load tools. With this feature we can access a vast range of tools and expand their agent’s capabilities

👏 Compatibility with Any LLM

SmolAgents supports models hosted on the Hugging Face Hub, either loaded through transformers or via the inference API. Additionally, it is compatible with other large language models (LLMs) such as OpenAI and Anthropic models through LiteLLM integration

SmolAgents makes it easy to create and manage AI-powered agents with minimal effort

• Easy to Use: Its simple design ensures that even developers new to AI agents can get started quickly.
• Secure: With sandboxed execution for Code Agents, security risks are minimized.
• Flexible: Whether you prefer code-based agents or JSON-based interactions, SmolAgents supports both.
• Scalable: Integration with Hugging Face Hub and multiple LLMs means users can scale their projects with ease

Lets create a simple Text to SQL agent:

A standard text-to-sql pipeline is brittle, since the generated SQL query can be incorrect. Even worse, the query could be incorrect, but not raise an error, instead giving some incorrect/useless outputs without raising an alarm

👉 Instead, an agent system is able to critically inspect outputs and decide if the query needs to be changed or not, thus giving it a huge performance boost

First let us begin by setting up a database with a table called receipts

from sqlalchemy import (
    create_engine,
    MetaData,
    Table,
    Column,
    String,
    Integer,
    Float,
    insert,
    inspect,
    text,
)

engine = create_engine("sqlite:///:memory:")
metadata_obj = MetaData()

# create city SQL table
table_name = "receipts"
receipts = Table(
    table_name,
    metadata_obj,
    Column("receipt_id", Integer, primary_key=True),
    Column("customer_name", String(16), primary_key=True),
    Column("price", Float),
    Column("tip", Float),
)
metadata_obj.create_all(engine)

rows = [
    {"receipt_id": 1, "customer_name": "Alan Payne", "price": 12.06, "tip": 1.20},
    {"receipt_id": 2, "customer_name": "Alex Mason", "price": 23.86, "tip": 0.24},
    {"receipt_id": 3, "customer_name": "Woodrow Wilson", "price": 53.43, "tip": 5.43},
    {"receipt_id": 4, "customer_name": "Margaret James", "price": 21.11, "tip": 1.00},
]
for row in rows:
    stmt = insert(receipts).values(**row)
    with engine.begin() as connection:
        cursor = connection.execute(stmt)

Now let’s make our SQL table retrievable by a tool

The tool’s description attribute will be embedded in the LLM’s prompt by the agent system: it gives the LLM information about how to use the tool. This is where we want to describe the SQL table

inspector = inspect(engine)
columns_info = [(col["name"], col["type"]) for col in inspector.get_columns("receipts")]

table_description = "Columns:\n" + "\n".join([f"  - {name}: {col_type}" for name, col_type in columns_info])
print(table_description)

Now let’s build our tool. It needs the following:

• A docstring with an Args: part listing arguments
• Type hints on both inputs and output

from smolagents import tool

@tool
def sql_engine(query: str) -> str:
    """
    Allows you to perform SQL queries on the table. Returns a string representation of the result.
    The table is named 'receipts'. Its description is as follows:
        Columns:
        - receipt_id: INTEGER
        - customer_name: VARCHAR(16)
        - price: FLOAT
        - tip: FLOAT

    Args:
        query: The query to perform. This should be correct SQL.
    """
    output = ""
    with engine.connect() as con:
        rows = con.execute(text(query))
        for row in rows:
            output += "\n" + str(row)
    return output

Now let us create an agent that leverages this tool.

We use the CodeAgent, which is smolagents’ main agent class: an agent that writes actions in code and can iterate on previous output according to the ReAct framework.

The model is the LLM that powers the agent system. HfApiModel allows you to call LLMs using HF’s Inference API, either via Serverless or Dedicated endpoint, but you could also use any proprietary API

from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[sql_engine],
    model=HfApiModel("meta-llama/Meta-Llama-3.1-8B-Instruct"),
)
agent.run("Can you give me the name of the client who got the most expensive receipt?")

It directly works! The setup was surprisingly simple, wasn’t it?

This example is done! We’ve touched upon these concepts:

• Building new tools.
• Updating a tool’s description.
• Switching to a stronger LLM helps agent reasoning