Smolagents Integration

Maxim AI provides comprehensive agent monitoring, evaluation, and observability for your Smolagents applications. With Maxim’s one-line integration, you can easily trace and analyze agent interactions, tool usage, and performance metrics.

Getting Started

Prerequisites

Python version >=3.10
A Maxim account (sign up here)
Generate Maxim API Key
A Smolagents project

Installation

Install the required packages via pip:

pip install maxim-py smolagents python-dotenv

Or add them to your requirements.txt:

maxim-py
smolagents
python-dotenv

Basic Setup

1. Set up environment variables

Create a .env file in your project root:

# Maxim API Configuration
MAXIM_API_KEY=your_api_key_here
MAXIM_LOG_REPO_ID=your_repo_id_here

# OpenAI API Configuration (for Smolagents)
OPENAI_API_KEY=your_openai_api_key_here

2. Import the required packages

from maxim import Maxim
from maxim.logger.smolagents import instrument_smolagents
from smolagents import OpenAIServerModel, CodeAgent
from dotenv import load_dotenv
import os

3. Initialize Maxim with your API key

# Load environment variables
load_dotenv()

# Instrument Smolagents with just one line
instrument_smolagents(Maxim().logger())

4. Create and run your Smolagents application

# Create your agent with tools
agent = CodeAgent(
    tools=[your_tools],  # Your custom tools
    model=OpenAIServerModel(
        model_id="gpt-4o-mini",
        api_key=os.environ["OPENAI_API_KEY"],
        api_base="https://api.openai.com/v1",
    ),
)

# Run your agent
result = agent.run("Your query here")

That’s it! All your Smolagents interactions will now be logged and available in your Maxim dashboard.

Complete Example

Here’s a complete example showing how to integrate Smolagents with Maxim, including a custom SQL tool:

from sqlalchemy import (
    Column,
    Float,
    Integer,
    MetaData,
    String,
    Table,
    create_engine,
    insert,
    inspect,
    text,
)
from maxim import Maxim
from maxim.logger.smolagents import instrument_smolagents
import os
from smolagents import OpenAIServerModel
from smolagents import CodeAgent
from smolagents import tool
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Initialize Maxim
instrument_smolagents(Maxim().logger())

# Set up SQL database
engine = create_engine("sqlite:///:memory:")
metadata_obj = MetaData()

# Create receipts 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)

# Insert sample data
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:
        connection.execute(stmt)

# Create SQL 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

# Create and run agent
agent = CodeAgent(
    tools=[sql_engine],
    model=OpenAIServerModel(
        model_id="gpt-4o-mini",
        api_key=os.environ["OPENAI_API_KEY"],
        api_base="https://api.openai.com/v1",
    ),
)

# Run the agent
result = agent.run("Can you give me the name of the client who got the most expensive receipt?")
print(result)

Viewing Your Traces

After running your Smolagents application:

Log in to your Maxim Dashboard
Navigate to your repository
View detailed agent traces, including:
- Agent conversations
- Tool usage patterns
- Performance metrics
- Cost analytics

Advanced Usage

Custom Tools with Maxim Integration

You can create custom tools and they will automatically be traced by Maxim:

@tool
def custom_tool(input_data: str) -> str:
    """
    A custom tool that processes input data.
    
    Args:
        input_data: The input string to process
        
    Returns:
        Processed result
    """
    # Your tool logic here
    result = f"Processed: {input_data}"
    return result

# Add to your agent
agent = CodeAgent(
    tools=[custom_tool, sql_engine],
    model=OpenAIServerModel(
        model_id="gpt-4o-mini",
        api_key=os.environ["OPENAI_API_KEY"],
    ),
)

Error Handling

Ensure proper cleanup even when errors occur:

try:
    result = agent.run("Your query here")
    print(result)
except Exception as e:
    print(f"Error: {e}")
finally:
    # Ensure Maxim cleanup happens
    maxim.cleanup()

Troubleshooting

Common Issues

No traces appearing: Ensure your API key and repository ID are correct
Import errors: Make sure you’ve installed all required packages (maxim-py, smolagents, python-dotenv)
Tool not working: Ensure instrument_smolagents() is called before creating your agent
Environment variables: Verify your .env file is in the correct location and contains all required keys

Debug Mode

Enable debug mode to surface any internal errors:

instrument_smolagents(Maxim().logger(), debug=True)

Overview

Python

Typescript

Smolagents Integration

Getting Started

Prerequisites

Installation

Basic Setup

1. Set up environment variables

2. Import the required packages

3. Initialize Maxim with your API key

4. Create and run your Smolagents application

Complete Example

Viewing Your Traces

Advanced Usage

Custom Tools with Maxim Integration

Error Handling

Troubleshooting

Common Issues

Debug Mode

Resources

Smolagents Docs

Github (smolagents cookbook)

​Getting Started

​Prerequisites

​Installation

​Basic Setup

​1. Set up environment variables

​2. Import the required packages

​3. Initialize Maxim with your API key

​4. Create and run your Smolagents application

​Complete Example

​Viewing Your Traces

​Advanced Usage

​Custom Tools with Maxim Integration

​Error Handling

​Troubleshooting

​Common Issues

​Debug Mode

​Resources

Smolagents Docs

Github (smolagents cookbook)

Getting Started

Prerequisites

Installation

Basic Setup

1. Set up environment variables

2. Import the required packages

3. Initialize Maxim with your API key

4. Create and run your Smolagents application

Complete Example

Viewing Your Traces

Advanced Usage

Custom Tools with Maxim Integration

Error Handling

Troubleshooting

Common Issues

Debug Mode

Resources