smolagents - Cheatsheet Code-First AI Agents

smolagents - Cheatsheet Code-First AI Agents

smolagents è una libreria agent minimalista e code-first da Hugging Face. L”idea centrale: invece di far emettere al modello tool call come blob JSON, un CodeAgent scrive ed esegue codice Python direttamente. Esprimere le azioni come codice permette a un singolo step di chiamare molteplici tool, usare loop e variabili, e concatenare logica — il che riduce il numero di round-trip LLM (circa ~30% in meno) e migliora la performance su task complessi. È model-agnostic, supporta esecuzione sandboxata, e rimane deliberatamente piccolo e hackable.

Installazione

Metodo	Comando
pip	pip install smolagents
Con tools extras	pip install "smolagents[toolkit]"
Sandbox extras	pip install "smolagents[e2b]" (o [docker])
Imposta una model key	export HF_TOKEN=... o provider keys
Verifica	python -c "import smolagents; print(''ok'')"

Concetti Principali

Termine	Significato
CodeAgent	Agent che scrive azioni Python (il default)
ToolCallingAgent	Agent che emette classiche JSON tool call
Tool	Un callable che l”agent può usare (con uno schema)
Model	Il backend LLM (HF, OpenAI, LiteLLM, local)
Sandbox	Dove il codice generato esegue (local, E2B, Docker, Modal)

Un CodeAgent Minimalista

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

agent = CodeAgent(
    tools=[WebSearchTool()],
    model=InferenceClientModel(),   # HF Inference API
)

agent.run("Quanti secondi occorrerebbero a un ghepardo per attraversare il Golden Gate Bridge?")

Oggetto	Ruolo
CodeAgent(tools=[...], model=...)	L”agent
agent.run("task")	Esegui un task end to end
WebSearchTool()	Un tool built-in
InferenceClientModel()	Backend modello HF-hosted

Modelli

Backend	Classe
HF Inference API	InferenceClientModel
Local transformers	TransformersModel
Qualsiasi provider via LiteLLM	LiteLLMModel(model_id="openai/gpt-4o")
OpenAI-compatible server	OpenAIServerModel(...)
vLLM / local endpoints	via LiteLLM / OpenAI-compatible

Definire Tool

from smolagents import tool

@tool
def get_weather(city: str) -> str:
    """Ritorna il weather per una città.

    Args:
        city: La città da cercare.
    """
    return f"Sunny in {city}"

agent = CodeAgent(tools=[get_weather], model=InferenceClientModel())

Meccanismo	Usa
@tool decorator	Trasforma una funzione tipizzata in un tool
Tool subclass	Più controllo su schema/behavior
Tool Collections	Importa set di tool (e.g. dal Hub)
MCP tools	Connetti server Model Context Protocol

Esecuzione Sandboxata (Importante)

Poiché CodeAgents eseguono Python generato, isolalo in produzione.

Sandbox	Come
Local (default)	Esegue in-process — ok solo per dev trusted
E2B	executor_type="e2b" (remote sandbox)
Docker	executor_type="docker"
Modal	Remote sandboxed execution
Allowed imports	Limita quali moduli il codice generato può importare

agent = CodeAgent(tools=[...], model=..., executor_type="e2b")

Multi-Agent & Retrieval

Pattern	Come
Managed agents	Dai a un agent altri agent come tool
Retrieval/RAG	Aggiungi un retriever tool per risposte grounded
Planning	Abilita periodic planning steps per task hard
Handoffs	Componi specialisti sotto un manager agent

Workflow Comuni

# Un research agent che naviga e computa in codice
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel(),
                  executor_type="docker")
agent.run("Compara la crescita della popolazione di Tokyo e Delhi dal 2000.")

smolagents vs Altri Framework di Agent

Aspetto	smolagents	LangGraph	Pydantic AI
Action format	Python code	Graph/state machine	Typed tool calls
Size/philosophy	Minimal, hackable	Full state orchestration	Type-safe, FastAPI-style
LLM efficiency	Fewer calls (code)	Depends	Standard
Best for	Single-agent code loops	Durable stateful agents	Type-safe production agents

Risorse

• GitHub Repository
• Official Documentation
• Guided Tour