Smolagents Integration Guide

This guide will walk you through integrating Smolagents with APIpie, enabling you to build powerful AI agents that leverage code execution for more complex reasoning and tool use.

What is Smolagents?

Smolagents is a minimalist, yet powerful library for building AI agents that think in code. It offers:

Code-First Agents: Agents that express their reasoning and actions as Python code (rather than JSON or natural language)
Minimalist Design: Core agent logic in ~1,000 lines of code, with minimal abstractions
Sandboxed Execution: Secure code execution with E2B or Docker sandboxing
Multi-Modal Support: Handle text, images, audio, and video inputs
Flexible Tool Integration: Use tools from various ecosystems or create your own
Model Agnosticism: Works with any LLM provider

By integrating Smolagents with APIpie, you can leverage APIpie's diverse model selection while building powerful, code-native agents that can reason through complex problems step by step.

Integration Steps

1. Create an APIpie Account

Register here: APIpie Registration
Complete the sign-up process.

2. Add Credit

Add Credit: APIpie Subscription
Add credits to your account to enable API access.

3. Generate an API Key

API Key Management: APIpie API Keys
Create a new API key for use with Smolagents.

4. Install Smolagents

pip install smolagents

For sandboxed execution (optional but recommended):

# For E2B sandboxing
pip install e2b

# Or for Docker-based sandboxing
# Make sure Docker is installed on your system

5. Configure Smolagents with APIpie

import os
from smolagents import CodeAgent, LiteLLMModel

# Configure the LLM using APIpie
model = LiteLLMModel(
    model_id="apipie/gpt-4o",  # Use any APIpie model
    api_key=os.environ.get("APIPIE_API_KEY"),
    api_base="https://apipie.ai/v1"
)

# Create a simple agent
agent = CodeAgent(model=model)

Key Features

Code as Actions: Agents express reasoning and actions as Python code, enabling more complex logic
Tool Integration: Easy creation and use of custom tools with typed inputs and outputs
Secure Execution: Multiple options for secure code execution (local, E2B, Docker)
Model Flexibility: Works with any LLM accessible through InferenceClient, OpenAI API, or LiteLLM
Modularity: Build multi-agent systems with specialized agents working together
Hub Integration: Share and reuse tools via Hugging Face Hub

Example Workflows

Application Type	What Smolagents Helps You Build
Research Assistants	Agents that can search, analyze, and synthesize information
Data Analysis	Code agents that can process, visualize, and interpret data
Web Browsing Agents	Agents that can navigate and extract information from the web
Multi-Agent Systems	Orchestrate multiple specialized agents to solve complex tasks
Tool-Using Applications	Apps that dynamically select and use appropriate tools

Using Smolagents with APIpie

Basic Agent with Web Search

import os
from smolagents import CodeAgent, DuckDuckGoSearchTool, LiteLLMModel

# Configure with APIpie
model = LiteLLMModel(
    model_id="apipie/gpt-4o-mini",
    api_key=os.environ.get("APIPIE_API_KEY"),
    api_base="https://apipie.ai/v1"
)

# Create an agent with search capability
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model
)

# Run the agent
result = agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")
print(result)

Creating Custom Tools

from smolagents import tool, CodeAgent, LiteLLMModel
import os

# Define a custom tool with the @tool decorator
@tool
def weather_forecast(city: str, days: int = 3) -> str:
    """Get weather forecast for a city.
    
    Args:
        city: The name of the city to get weather for
        days: Number of days to forecast (default: 3)
        
    Returns:
        A string with the weather forecast
    """
    # In a real implementation, you would call a weather API here
    return f"Weather forecast for {city} for the next {days} days: Sunny, 25°C"

# Create the agent with APIpie model
model = LiteLLMModel(
    model_id="apipie/claude-3-opus-20240229",
    api_key=os.environ.get("APIPIE_API_KEY"),
    api_base="https://apipie.ai/v1"
)

agent = CodeAgent(
    tools=[weather_forecast],
    model=model
)

response = agent.run("What's the weather in Paris and should I pack an umbrella for my trip?")
print(response)

import os
import base64
from pathlib import Path
from smolagents import CodeAgent, LiteLLMModel, DuckDuckGoSearchTool

# Configure APIpie with a vision-capable model
model = LiteLLMModel(
    model_id="apipie/gpt-4o",  # Use a vision-capable model
    api_key=os.environ.get("APIPIE_API_KEY"),
    api_base="https://apipie.ai/v1"
)

# Create the agent
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model
)

# Read an image file
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

# Create a query with an image
image_path = "path/to/your/image.jpg"
base64_image = encode_image(image_path)
image_content = {
    "type": "image_url",
    "image_url": {
        "url": f"data:image/jpeg;base64,{base64_image}"
    }
}

# Run the agent with multimodal input
response = agent.run([
    {"role": "user", "content": [
        {"type": "text", "text": "What's in this image? Can you identify the landmarks?"},
        image_content
    ]}
])

print(response)

Sandboxed Execution with E2B

import os
from smolagents import CodeAgent, LiteLLMModel, DuckDuckGoSearchTool
from smolagents.code_interpreters import E2BInterpreter

# Set up your E2B API key
os.environ["E2B_API_KEY"] = "your-e2b-api-key"

# Create APIpie model
model = LiteLLMModel(
    model_id="apipie/mistral-large-2",
    api_key=os.environ.get("APIPIE_API_KEY"),
    api_base="https://apipie.ai/v1"
)

# Create the agent with E2B sandboxed execution
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
    code_interpreter=E2BInterpreter()  # Use E2B for secure code execution
)

response = agent.run("Analyze the GDP growth trends of the top 5 economies over the last decade and create a visualization.")
print(response)

from smolagents import tool, CodeAgent, LiteLLMModel
import os

@tool
def currency_converter(amount: float, from_currency: str, to_currency: str) -> float:
    """Convert an amount from one currency to another.
    
    Args:
        amount: The amount to convert
        from_currency: The source currency code (e.g., USD, EUR)
        to_currency: The target currency code (e.g., USD, EUR)
        
    Returns:
        The converted amount
    """
    # In a real implementation, you would call a currency API
    rates = {"USD": 1.0, "EUR": 0.92, "GBP": 0.78, "JPY": 153.2}
    if from_currency not in rates or to_currency not in rates:
        raise ValueError(f"Currency not supported: {from_currency} or {to_currency}")
    
    # Convert to USD first, then to target currency
    usd_amount = amount / rates[from_currency]
    target_amount = usd_amount * rates[to_currency]
    return round(target_amount, 2)

# Share the tool to Hugging Face Hub
currency_converter.push_to_hub("your-username/currency-converter-tool")

Agent CLI Tools

Smolagents provides convenient CLI tools for quickly launching agents:

# Run a general-purpose agent with web search capability
smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7." \
  --model-type "LiteLLMModel" \
  --model-id "apipie/gpt-4o" \
  --tools "web_search"

# Run a web browsing agent
webagent "Go to xyz.com/products, find the bestselling item, and summarize its features" \
  --model-type "LiteLLMModel" \
  --model-id "apipie/gpt-4o"

Troubleshooting & FAQ

How do I ensure code execution is secure?
Use the E2B or Docker sandbox options to isolate agent code execution from your system. Never run untrusted code directly in your environment.
Which APIpie models work best with Smolagents?
Models with strong code generation capabilities like GPT-4o, Claude 3 Opus, and DeepSeek Coder perform best for code agents.
How do I handle rate limits?
You can implement retry logic in your agent setup or use LiteLLM's built-in retry mechanisms.
Can I use multiple models in the same agent system?
Yes, each agent can use a different model. You might use a powerful model for reasoning and planning, and a more cost-effective model for simpler tasks.
How do I debug agent execution?
Set verbose=True when creating your agent to see detailed logs of the agent's thinking and execution.
What's the difference between CodeAgent and ToolCallingAgent?
CodeAgent writes its actions as Python code, which enables more complex logic and control flow. ToolCallingAgent uses a more traditional JSON-based tool calling approach.

For more information, see the Smolagents documentation or the GitHub repository.

Support

If you encounter any issues during the integration process, please reach out on APIpie Discord or Hugging Face Discord for assistance.

What is Smolagents?​

Integration Steps​

1. Create an APIpie Account​

2. Add Credit​

3. Generate an API Key​

4. Install Smolagents​

5. Configure Smolagents with APIpie​

Key Features​

Example Workflows​

Using Smolagents with APIpie​

Basic Agent with Web Search​

Creating Custom Tools​

Multi-Modal Agent with Vision​

Sandboxed Execution with E2B​

Sharing Tools to the Hub​

Agent CLI Tools​

Troubleshooting & FAQ​

Support​