smolagents - Cheatsheet Agents IA Orientés Code

smolagents - Cheatsheet Agents IA Orientés Code

smolagents est une bibliothèque d”agents minimaliste et orientée code de Hugging Face. Son idée centrale : au lieu de faire émettre au modèle les appels d”outils en tant que blobs JSON, un CodeAgent écrit et exécute du code Python directement. Exprimer les actions en tant que code permet à une seule étape d”appeler plusieurs outils, utiliser des boucles et des variables, et chaîner la logique — ce qui réduit le nombre de round-trips LLM (environ 30% moins) et améliore les performances sur les tâches complexes. Il est agnostique au modèle, supporte l”exécution en sandbox et reste délibérément petit et modifiable.

Installation

Méthode	Commande
pip	pip install smolagents
Avec extras toolkit	pip install "smolagents[toolkit]"
Extras sandbox	pip install "smolagents[e2b]" (ou [docker])
Définir une clé modèle	export HF_TOKEN=... ou les clés du fournisseur
Vérification	python -c "import smolagents; print(''ok'')"

Concepts Principaux

Terme	Signification
CodeAgent	Agent qui écrit des actions Python (le défaut)
ToolCallingAgent	Agent qui émet les appels d”outils JSON classiques
Tool	Un callable que l”agent peut utiliser (avec un schéma)
Model	Le backend LLM (HF, OpenAI, LiteLLM, local)
Sandbox	Où le code généré s”exécute (local, E2B, Docker, Modal)

Un CodeAgent Minimaliste

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

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

agent.run("How many seconds would it take a cheetah to cross the Golden Gate Bridge?")

Objet	Rôle
CodeAgent(tools=[...], model=...)	L”agent
agent.run("task")	Exécuter une tâche de bout en bout
WebSearchTool()	Un outil intégré
InferenceClientModel()	Backend de modèle hébergé HF

Modèles

Backend	Classe
API HF Inference	InferenceClientModel
Transformateurs locaux	TransformersModel
N”importe quel fournisseur via LiteLLM	LiteLLMModel(model_id="openai/gpt-4o")
Serveur compatible OpenAI	OpenAIServerModel(...)
vLLM / endpoints locaux	via LiteLLM / compatible OpenAI

Définir des Tools

from smolagents import tool

@tool
def get_weather(city: str) -> str:
    """Return the weather for a city.

    Args:
        city: The city to look up.
    """
    return f"Sunny in {city}"

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

Mécanisme	Utilisation
Décorateur @tool	Transformer une fonction typée en outil
Sous-classe Tool	Plus de contrôle sur le schéma/comportement
Collections de Tools	Importer des ensembles d”outils (ex. depuis le Hub)
Tools MCP	Connecter les serveurs Model Context Protocol

Exécution en Sandbox (Important)

Parce que les CodeAgents exécutent du Python généré, isolez-le en production.

Sandbox	Comment
Local (défaut)	S”exécute in-process — ok uniquement pour le dev fiable
E2B	executor_type="e2b" (sandbox distant)
Docker	executor_type="docker"
Modal	Exécution distante en sandbox
Imports autorisés	Restreindre les modules que le code généré peut importer

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

Multi-Agent et Retrieval

Pattern	Comment
Agents gérés	Donner à un agent d”autres agents en tant que tools
Retrieval/RAG	Ajouter un outil retriever pour les réponses fondées
Planification	Activer les étapes de planification périodique pour les tâches dures
Handoffs	Composer les spécialistes sous un agent manager

Flux de Travail Courants

# Un agent de recherche qui navigue et calcule en code
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel(),
                  executor_type="docker")
agent.run("Compare the population growth of Tokyo and Delhi since 2000.")

smolagents vs Autres Frameworks d”Agent

Aspect	smolagents	LangGraph	Pydantic AI
Format action	Code Python	Graphe/machine à états	Appels d”outils typés
Taille/philosophie	Minimaliste, modifiable	Orchestration stateful complète	Typé-sûr, style FastAPI
Efficacité LLM	Moins d”appels (code)	Dépend	Standard
Meilleur pour	Boucles code agent simple	Agents stateful durables	Agents production typé-sûrs

Ressources

• Dépôt GitHub
• Documentation Officielle
• Guided Tour