smolagents

smolagents est une bibliothèque Python permettant de créer des agents IA autonomes, publiée par Hugging Face le 31 décembre 2024. Le principe central de la bibliothèque est que les agents doivent écrire et exécuter du code Python pour entreprendre des actions, plutôt que de générer des dictionnaires d'appels d'outils JSON comme le font la plupart des autres frameworks. La logique principale de l'agent tient en environ 1 000 lignes de code, ce qui est un choix délibéré : l'ensemble du framework est lisible, auditable et modifiable en une après-midi. Sous licence Apache 2.0, smolagents a atteint 27 000 étoiles GitHub en mai 2026, ce qui en fait l'un des frameworks d'agents adoptés le plus rapidement depuis LangChain.

La bibliothèque propose deux types d'agents : CodeAgent, qui génère des extraits Python en guise d'actions et les exécute dans un interpréteur en bac à sable (produisant 30 % d'appels LLM en moins par rapport à l'utilisation d'outils basés sur JSON), et ToolCallingAgent, qui suit le format standard d'appel d'outils JSON pour une compatibilité avec les API de type OpenAI. Elle prend en charge plus de 100 backends de modèles via LiteLLM, y compris l'inférence locale via Ollama et Hugging Face Transformers, ainsi qu'OpenAI, Anthropic et tout fournisseur disposant d'un point de terminaison compatible OpenAI. Les agents et les outils peuvent être partagés et récupérés depuis le Hugging Face Hub. Les entrées multimodales (texte, vision, vidéo, audio) sont prises en charge. Les options d'exécution en bac à sable incluent les environnements E2B, Modal, Docker, Blaxel et WebAssembly pour les équipes exécutant du code non fiable en production.

Ce que fait réellement smolagents en avril 2026

smolagents exécute une boucle de raisonnement en plusieurs étapes : l'agent reçoit une tâche, demande au LLM ce qu'il doit faire ensuite, exécute l'action résultante (sous forme de code Python ou d'appel d'outil), observe le résultat et répète l'opération jusqu'à ce que la tâche soit terminée ou que la limite d'étapes soit atteinte. La variante CodeAgent convertit cela en Python exécutable à chaque étape plutôt qu'en un objet d'action JSON. Un agent fonctionnel minimal nécessite trois lignes de Python : importer la bibliothèque, instancier un CodeAgent avec une liste d'outils et un modèle, puis appeler agent.run("your task").

La version 1.24.0 (janvier 2026) a étendu l'architecture multi-agents, où un CodeAgent gestionnaire peut déléguer des sous-tâches à des sous-agents spécialisés. L'intégration au Hub signifie que tout outil ou configuration d'agent publié sur le Hugging Face Hub peut être importé en une seule ligne. La compatibilité avec les serveurs MCP a été ajoutée début 2025, permettant à smolagents de consommer des outils exposés via le Model Context Protocol aux côtés d'outils Python natifs et d'outils compatibles LangChain.

Le résultat du benchmark GAIA lors de la période de lancement de la bibliothèque a établi sa crédibilité : un CodeAgent construit avec l'architecture smolagents a obtenu un score de 44,2 % sur l'ensemble de validation GAIA (classé premier au lancement), battant AutoGen de Microsoft à 40 % et se situant bien au-dessus du score de base de GPT-4-Turbo de moins de 7 % sur le même benchmark sans framework d'agent. GAIA teste la planification de haut niveau, le raisonnement multimodal et la collecte d'informations en plusieurs étapes sur des tâches complexes telles que l'identification d'œuvres d'art, la mise en correspondance de documents historiques et le traitement de données structurées. Fin 2025, des optimisations supplémentaires ont poussé les systèmes basés sur smolagents à 55 % sur GAIA, renforçant l'avantage de l'approche axée sur le code pour les tâches nécessitant des calculs composables et avec état.

Où se situe smolagents par rapport à LangChain et PydanticAI

Les trois comparaisons les plus citées pour smolagents sont LangChain/LangGraph (le leader dominant), PydanticAI (le nouveau venu axé sur la sécurité des types) et, dans une moindre mesure, LlamaIndex. Chacun représente une philosophie différente de ce que devrait être un framework d'agent.

LangChain et LangGraph comptent plus de 90 000 étoiles GitHub et cinq ans d'historique en production. LangGraph étend LangChain avec une architecture de graphe orienté acyclique (DAG) où les étapes de l'agent sont des nœuds de graphe explicites, offrant aux développeurs un contrôle précis sur la logique de branchement, les machines à états, les tentatives et la propagation des erreurs. Ce contrôle s'accompagne d'un certain formalisme : définir un flux de travail LangGraph nécessite des définitions explicites de nœuds, d'arêtes et de schémas d'état avant même qu'une seule action ne s'exécute. smolagents gère automatiquement la boucle ReAct dans son cœur de 1 000 lignes ; vous fournissez des outils et un modèle, et la boucle est gérée pour vous. LangGraph est le bon choix pour une orchestration complexe avec état, avec des points de contrôle impliquant une validation humaine (human-in-the-loop) et une gestion fine des erreurs. smolagents est plus rapide pour le prototypage mais moins contrôlable à grande échelle.

PydanticAI, sorti en septembre 2024 et ayant atteint la v1.0 en septembre 2025, apporte au développement d'agents une validation structurée de type FastAPI. Chaque appel d'outil et sortie d'agent est validé par rapport à des schémas Pydantic avant traitement, avec une instrumentation OpenTelemetry intégrée et une conception asynchrone en priorité. La différence mécanique de PydanticAI par rapport à smolagents réside dans l'application des sorties : là où smolagents produit tout le code Python que le LLM écrit et fait confiance à la validité du code, PydanticAI impose des contrats de schéma à chaque frontière. Pour les dossiers médicaux, les pipelines de données financières ou toute application nécessitant des réponses structurées auditables et prévisibles, les garanties de validation de PydanticAI sont essentielles. smolagents n'offre aucun mécanisme équivalent. Le compromis est que le typage strict de PydanticAI ajoute une surcharge de configuration que smolagents évite délibérément.

Pour les équipes déjà investies dans l'écosystème Hugging Face, utilisant Transformers ou des modèles open source via Ollama, ou construisant des prototypes de recherche, smolagents a un net avantage sur son terrain. Pour les équipes exécutant des applications de production qui traitent des données structurées sensibles, le contrôle de LangGraph ou la validation de PydanticAI valent la complexité supplémentaire. Les utilisateurs associent souvent smolagents au Hub Hugging Face pour l'accès aux modèles et le partage d'outils, ou aux outils LangChain via la couche de compatibilité LangChain de smolagents.

"Si les extraits JSON étaient une meilleure expression, JSON serait le premier langage de programmation et la programmation serait un enfer sur terre." - Aymeric Roucher, Merve Noyan et Thomas Wolf, équipe d'ingénierie de Hugging Face, blog de lancement de smolagents, décembre 2024

À quoi ressemble la réalité de la boucle d'agent

Exécuter un CodeAgent dans smolagents signifie que le LLM génère du code Python à chaque étape. Cela fonctionne bien lorsque le modèle a une forte capacité de génération de code. Dans le cas contraire, la boucle se dégrade rapidement : l'agent écrit du code Python syntaxiquement incorrect, l'interpréteur lève une exception, l'erreur est ajoutée au contexte et il est demandé au LLM de la corriger. Sur des modèles performants (GPT-4o, Claude Sonnet, DeepSeek-R1, Qwen2.5-Coder), cette boucle d'autocorrection est robuste. Sur des modèles plus petits à usage général, elle produit une spirale frustrante de code défaillant qui brûle des tokens sans faire de progrès.

La gestion de la mémoire est la frustration la plus fréquemment citée dans les tickets GitHub. L'agent conserve un historique complet de chaque action et observation. Sur les tâches longues, cet historique dépasse la fenêtre de contexte du modèle. Contrairement à l'approche de résumé de Claude Code (qui compresse l'ancien contexte de manière continue), smolagents, début 2026, ne dispose d'aucune consolidation de mémoire intégrée. Le ticket GitHub #694 décrit directement le problème : "troncature de base et suppression de messages, mais AUCUN résumé intégré pour gérer la croissance de la mémoire à long terme." Le ticket #901, déposé en mars 2025, confirme que "les outils liés à la mémoire ne sont pas encore exposés dans smolagents, ce qui est une limitation pour les applications d'agents plus avancées." Le ticket #1121 (avril 2025) est une demande de fonctionnalité pour une banque de mémoire persistante à long terme. Ce sont des lacunes connues sur la feuille de route publique.

L'exécution de code en bac à sable est documentée mais structurée en couches. L'exécution locale du CodeAgent utilise un interpréteur Python restreint (basé sur l'AST, avec des contrôles d'importation et des limites de nombre d'opérations). Pour une isolation plus stricte, les bacs à sable E2B, Modal, Docker et WebAssembly sont disponibles, mais l'architecture multi-agents ne prend actuellement pas en charge les exécuteurs en bac à sable, ce qui signifie que l'agent gestionnaire et ses sous-agents s'exécutent dans le même contexte d'exécution. Les déploiements en production gérant des entrées non fiables doivent explicitement contourner cette limitation dans leur architecture.

"Il y a un grand pas entre ce que fait actuellement smolagents et tout ce dont vous avez besoin pour un framework d'agent exécutant une application de niveau production." - revue du framework par agentsdecoded.com, 2025

Les utilisateurs qui créent des flux de travail de recherche et de science des données signalent l'expérience la plus fluide. Un modèle typique : définir 5 à 10 outils (recherche DuckDuckGo, un REPL Python, un lecteur de fichiers, un client API), instancier un CodeAgent et lui confier une tâche de recherche ouverte. L'agent compose du code Python qui enchaîne les appels d'outils, traite les résultats intermédiaires dans des variables et renvoie une sortie structurée sans que le développeur n'ait à écrire de logique d'orchestration. Les utilisateurs associent fréquemment smolagents à DSPy pour l'optimisation des prompts ou à PydanticAI pour la validation des sorties dans des pipelines hybrides.

À qui s'adresse smolagents

smolagents convient aux chercheurs en ML, aux data scientists et aux développeurs backend qui pensent déjà en Python et souhaitent une surcharge minimale du framework. L'intégration à l'écosystème Hugging Face (modèles du Hub, outils du Hub, Transformers, Datasets) en fait le premier choix naturel pour les équipes déjà familières avec cette stack. Si le déploiement de votre modèle est Ollama exécutant Llama ou Qwen localement, ou un modèle affiné sur Hugging Face Inference Endpoints, smolagents est le point de départ évident : l'intégration est native, la licence est compatible et la base de code est suffisamment petite pour être lue et corrigée.

Les utilisateurs de modèles open source en bénéficient particulièrement car smolagents traite tous les modèles sur un pied d'égalité grâce à la compatibilité LiteLLM. Il n'y a pas de niveau premium pour les modèles restreints ou les optimisations propriétaires. Le même CodeAgent qui s'exécute avec GPT-4o peut s'exécuter avec un modèle Qwen2.5-Coder local avec un seul changement de configuration. Les équipes explorant des architectures d'agents sans dépendance vis-à-vis d'un fournisseur apprécieront cette flexibilité. Pour explorer la coordination multi-agents, le modèle d'agents gérés (où un agent de niveau supérieur orchestre des sous-agents) fonctionne de manière native sans configuration supplémentaire. La bibliothèque complète LlamaIndex dans les pipelines où la génération augmentée par la recherche (RAG) alimente un agent qui traite le contexte récupéré avec du code.

Ce que smolagents n'est pas

smolagents n'est pas une plateforme d'agents d'entreprise de niveau production. Elle ne dispose d'aucune observabilité intégrée, de journalisation structurée ou de politiques de tentatives au-delà de ce que le développeur ajoute manuellement. Il n'y a pas de sorties imposées par des schémas, pas de piste d'audit native et pas de certifications de conformité. Les équipes des secteurs réglementés (santé, finance, juridique) évaluant des frameworks d'agents pour des déploiements en production trouveront que les contrats de validation de PydanticAI ou la gestion d'état explicite de LangGraph correspondent mieux à leurs exigences de gouvernance.

Elle ne pardonne pas non plus les modèles faibles. L'approche axée sur le code nécessite un LLM qui écrit du code Python propre et fonctionnel sous la pression des prompts. Tenter d'exécuter smolagents avec des modèles à usage général plus petits (en dessous d'environ 7 milliards de paramètres, ou des modèles non spécifiquement entraînés sur du code) produit des résultats peu fiables. Il s'agit d'une véritable contrainte matérielle et de coût pour les équipes souhaitant tout auto-héberger sur des GPU grand public.

Enfin, smolagents n'est pas un outil d'orchestration de flux de travail au sens de LangGraph. Si votre cas d'usage nécessite une logique de branchement explicite (acheminer la tâche A vers le sous-agent X, la tâche B vers le sous-agent Y en fonction d'un classificateur), des tentatives conditionnelles avec persistance d'état ou des étapes d'approbation humaine, LangGraph vous offre ces primitives. smolagents les abstrait, ce qui est sa force pour les cas simples et sa limite pour les cas complexes. Les équipes qui ont dépassé la boucle ReAct automatique et qui ont besoin d'un contrôle d'orchestration précis devraient considérer smolagents comme une phase de prototypage avant de migrer vers un framework plus explicite comme LangGraph ou CrewAI.