description: Definitive guidelines for building robust, performant, and maintainable AI agents using smolagents, focusing on practical patterns and avoiding common pitfalls.

smolagents Best Practices

This guide outlines the definitive best practices for developing smolagents applications. Adhering to these principles ensures your agents are reliable, efficient, and easy to maintain.

1. Code Organization and Structure

Organize your agent logic and tools into clear, distinct modules. This improves readability, reusability, and testability.

❌ BAD: Monolithic agent file

# agent.py
from smolagents import CodeAgent, HfApiModel, tool
import requests # Direct import in agent file

@tool
def search_web(query: str) -> str:
    # ... complex search logic ...
    return "search result"

@tool
def calculate_math(expression: str) -> float:
    # ... math logic ...
    return eval(expression) # DANGER! Unsafe!

agent = CodeAgent(tools=[search_web, calculate_math], model=HfApiModel())
agent.run("What is 2+2 and also search for 'latest AI news'")

✅ GOOD: Modular structure

# src/tools.py
from smolagents import tool
import requests
import json

@tool
def web_search(query: str) -> str:
    """
    Performs a web search for the given query.
    Args:
        query: The search term.
    Returns:
        A summary of the search results or an error message.
    """
    try:
        # Replace with a real search API (e.g., DuckDuckGoSearchTool, custom API)
        response = requests.get(f"https://api.example.com/search?q