Agents IA avec smolagents : quand miser sur Python

Choisissez smolagents pour créer des agents IA qui doivent combiner à la volée outils et calculs en Python, à condition de pouvoir exécuter ce code dans un environnement contrôlé. Hugging Face propose 2 classes d’agents, CodeAgent et ToolCallingAgent : la différence tient à la manière dont le modèle exprime son action suivante, en Python ou sous forme d’un appel d’outil structuré. Ce minimalisme convient bien à la résolution de problèmes délimités. La persistance des workflows, les permissions et l’isolation restent toutefois à votre charge.

Informations vérifiées dans la documentation en ligne de Hugging Face, LangChain et OpenAI le 31 octobre 2026. Les recommandations qui suivent portent sur la composition des actions, le contrôle des workflows et les périmètres d’exécution. Elles relèvent de choix d’architecture, pas de benchmarks de performance.

Comment smolagents fait agir les agents IA en Python

smolagents est la bibliothèque Python open source de Hugging Face qui permet de créer des agents dont les actions peuvent prendre la forme de code exécutable. Un agent fonctionne selon une boucle pilotée par un modèle : il choisit une action, observe son résultat, puis décide de la suite. CodeAgent exprime cette action en Python ; ToolCallingAgent passe par des appels d’outils structurés. Les deux reçoivent un modèle et un ensemble d’outils. Référence des agents Hugging Face.

Imaginez CodeAgent comme un chercheur autorisé à écrire un petit script entre deux observations. Il peut demander des enregistrements à un outil autorisé, transformer les données reçues et calculer une réponse. Vous fournissez les capacités et les contraintes ; le modèle écrit une partie du code qui les relie.

Ce fonctionnement diffère de celui d’un assistant qui vous livre un fichier de code à relire. Ici, le code généré est le moyen par lequel l’agent accomplit sa prochaine action.

Pour comparer les solutions, demandez-vous quelle partie de votre application doit rester souple :

Les deux dernières lignes reflètent les priorités mises en avant dans la documentation de LangGraph et de l’OpenAI Agents SDK, sans prétendre que ces capacités leur sont exclusives. Le choix dépend de l’endroit où vous attendez du framework qu’il structure votre application.

CodeAgent de smolagents : laisser le modèle composer les actions

CodeAgent trouve son intérêt lorsque les opérations intermédiaires s’expriment plus facilement en Python que dans une liste d’appels prédéfinis. Hugging Face cite les boucles, les conditions et les combinaisons d’outils parmi ses atouts, tout en rappelant la nécessité de gérer les erreurs de syntaxe, les exceptions et les comportements inattendus. Visite guidée.

Prenons le cas d’un développeur qui recherche des incohérences dans un inventaire. Un outil de consultation en lecture seule renvoie des enregistrements à examiner. L’agent peut avoir besoin d’harmoniser les noms, de regrouper les entrées similaires et de calculer la somme d’un champ avant de décider quels enregistrements consulter à nouveau. Python se prête naturellement à ces opérations intermédiaires.

Le résultat de l’exécution sert d’élément d’appréciation pour la décision suivante du modèle. Un calcul qui échoue constitue une observation à laquelle l’agent peut réagir ; cela ne garantit pas qu’il saura corriger son erreur.

ToolCallingAgent : limiter les actions à un ensemble défini

ToolCallingAgent est un meilleur point de départ lorsque vos opérations reposent déjà sur des contrats bien définis. Il produit des appels JSON structurés, avec des noms d’outils et des arguments, plutôt que de générer des actions en Python. Comparaison de Hugging Face.

Un assistant de support qui consulte une commande et récupère une politique applicable n’a pas forcément besoin de plus. Confiez les transformations prévisibles au code applicatif classique. Ajouter du Python généré à un workflow qui tient déjà dans des fonctions bien définies introduit une nouvelle source d’échec sans bénéfice évident.

Les appels structurés exigent eux aussi des contrôles d’autorisation. Une demande d’annulation de commande parfaitement formée peut être inappropriée pour le client concerné. Le schéma indique au programme ce qui a été demandé ; c’est à votre application de décider si l’opération est permise.

Choisir les outils et le modèle séparément

Limitez le périmètre des outils et choisissez le modèle indépendamment. Cette séparation fait l’intérêt pratique de smolagents : vous pouvez changer la manière dont l’agent raisonne sans redéfinir chaque capacité métier.

Un outil est une fonction au contrat exploitable

Dans smolagents, un outil encapsule une fonction avec un nom, une description, des métadonnées d’entrée et un type de sortie. Le décorateur @tool convient aux fonctions simples dotées d’annotations de type et d’une docstring utile. Pour un outil plus élaboré, créez une sous-classe de Tool et placez sa logique d’exécution dans forward. Guide des outils.

Pour un assistant d’inventaire, préférez une capacité comme « rechercher des enregistrements dans le catalogue autorisé » à un accès sans restriction à la base de données. Intégrez dans l’implémentation les contrôles d’appartenance au client, les restrictions de requête et les limites de réponse. Un prompt convaincant ne remplace pas ces contrôles.

Les outils peuvent aussi provenir de Model Context Protocol, ou MCP, une interface standard qui expose des outils aux applications utilisant des modèles, ainsi que d’adaptateurs pour les outils LangChain et Hugging Face Spaces. Réutiliser un outil ne suffit pas à garantir la fiabilité de son implémentation. Hugging Face exige explicitement trust_remote_code=True pour charger des outils du Hub, car ils exécutent du code personnalisé. Documentation sur l’intégration et le chargement des outils.

C’est donc une décision qui relève de la revue de code. Examinez l’implémentation de l’outil et ses dépendances avant de le mettre à disposition d’un agent.

Le backend du modèle ne détermine pas la sandbox

La référence actuelle des modèles décrit plusieurs possibilités :

• InferenceClientModel se connecte via Hugging Face Inference Providers.
• LiteLLMModel utilise la couche d’intégration des fournisseurs de LiteLLM.
• TransformersModel exécute un modèle Transformers en local.
• OpenAIModel se connecte à un serveur de modèles compatible avec OpenAI.

La visite guidée présente également Ollama pour l’inférence locale. Il s’agit de choix de backend, sans garantie que tous les modèles soient aussi efficaces pour générer du code ou sélectionner des outils.

Distinguez bien deux questions : où s’exécute le modèle, et où s’exécute le Python qu’il génère ? Un modèle hébergé peut piloter un exécuteur Docker. Un modèle local peut tout de même produire des actions dangereuses. Déplacer l’inférence sur votre machine ne crée pas de périmètre d’exécution isolé.

Pour assurer la reproductibilité, configurez explicitement votre modèle dès que vous dépassez le stade de la démonstration. Hugging Face précise que le modèle par défaut d’InferenceClientModel peut changer. Configuration du modèle.

Un exemple simple tiré de la documentation

Commencez par le calcul proposé dans la documentation pour comprendre le chemin d’exécution avant d’ajouter des outils. L’exemple d’introduction de Hugging Face demande la somme des nombres de 1 à 10, sans aucun outil. La version ci-dessous reprend cette tâche et y ajoute le gestionnaire de contexte Docker présenté dans le guide des sandbox. Exemple d’origine, configuration de l’exécution dans Docker.

1. 1

   Préparer l’environnement

   Le guide d’installation exige Python 3.10 ou une version ultérieure et recommande un environnement virtuel. Pour cet exemple, Docker doit également être installé et démarré. Guide d’installation.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Définissez HF_TOKEN dans votre environnement avec un jeton Hugging Face autorisé à appeler Inference Providers. InferenceClientModel peut lire cette variable automatiquement. Ne placez pas le jeton dans le script. Fonctionnement de l’authentification.

2. 2

   Exécuter la tâche de la documentation dans Docker

   Enregistrez ce code dans sum_agent.py :

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   Puis lancez :

   python sum_agent.py

   Le gestionnaire de contexte se charge du nettoyage de la sandbox à la sortie du bloc. Ce code est une adaptation de la documentation ; il ne s’agit pas du résultat d’un test exécuté pour cet article.

3. 3

   Vérifier le résultat et le périmètre d’exécution

   Le résultat mathématique attendu est 55, obtenu par 10 × 11 ÷ 2. Le modèle choisit le Python qu’il génère : ne vous attendez donc pas à un déroulé exact ni à une formulation identique à chaque exécution.

   tools=[] signifie qu’aucun outil personnalisé n’a été fourni. CodeAgent conserve pour autant sa capacité à exécuter du Python. C’est le réglage de l’exécuteur qui place ce code généré dans Docker.

Pour ce calcul fixe, du Python classique reste le choix raisonnable dans une application. L’exemple sert à montrer la mécanique de l’agent. Ajoutez un agent lorsque le choix des étapes intermédiaires fait partie du problème, pas simplement parce que le calcul peut se décrire en langage naturel.

Un agent qui exécute du code a besoin d’une sandbox

Considérez le Python généré comme du code non fiable et prévoyez une sandbox explicite avant de l’exposer à des entrées non fiables. L’exécuteur local par défaut est un interpréteur restreint ; il ne garantit pas l’isolation de votre machine hôte. Hugging Face cite parmi les risques les erreurs du modèle, l’injection de prompt et les requêtes malveillantes. Exécution sécurisée du code.

L’interpréteur local évalue opération par opération l’arbre syntaxique abstrait du programme Python, c’est-à-dire sa structure après analyse syntaxique. Il restreint les imports et les sous-modules, et plafonne le nombre d’opérations. Ces contrôles réduisent l’exposition, mais le guide de sécurité souligne que l’exécution locale reste risquée. Autoriser un paquet supplémentaire élargit ce à quoi le programme généré peut accéder.

Quelles sandbox Hugging Face prend-il en charge ?

L’API actuelle des exécuteurs prend en charge Blaxel, E2B, Modal et Docker, en plus de l’exécuteur local. Les noms de configuration ci-dessous correspondent à la référence de CodeAgent et à celle des exécuteurs.

Le choix du fournisseur et des identifiants d’accès se fait séparément de ces réglages. La documentation d’installation recense les dépendances optionnelles ; en installer une ne suffit pas à configurer un déploiement.

Pour une expérimentation interne, Docker peut fournir un périmètre d’exécution concret que vous pouvez examiner. Pour un service qui traite des requêtes non fiables, choisissez l’environnement en fonction de vos besoins d’isolation, de gestion du cycle de vie et de contrôle opérationnel. Le comparatif des sandbox d’exécution de code pour agents IA approfondit ce choix d’infrastructure.

Isoler les extraits de code ne revient pas à isoler tout l’agent

Décidez de ce qui doit se trouver dans le périmètre isolé avant d’ajouter d’autres agents. Hugging Face distingue l’exécution des extraits de code générés dans une sandbox de l’exécution de tout le système d’agents dans cet environnement. Son guide de sécurité avertit que l’approche limitée aux extraits ne prend pas en charge les agents gérés, c’est-à-dire les agents qu’un autre agent appelle en renfort. Placer l’ensemble du système à l’intérieur demande davantage de configuration et peut nécessiter de lui fournir des identifiants d’accès. Approches d’isolation.

La conséquence porte sur l’architecture. Si un futur agent spécialisé doit appeler un modèle depuis l’environnement d’exécution, le schéma initial « envoyer du code, recevoir un résultat » risque de ne plus suffire. Réexaminez l’emplacement des identifiants et les dépendances des outils lorsque vous modifiez l’organisation du déploiement.

Pour un service destiné aux clients, définissez les fichiers accessibles, les destinations réseau autorisées et les opérations appelables avant de démarrer l’agent. N’accordez à chaque exécution que les accès nécessaires à sa tâche. Prévoyez le dépassement de délai, l’annulation et le nettoyage comme des cas normaux du fonctionnement, y compris lorsque le modèle ne termine pas.

Choisir son framework d’agent IA : où le minimalisme aide

Choisissez le framework en fonction du problème de contrôle le plus difficile de votre application. Une initialisation courte est appréciable, mais le code que vous devez écrire autour compte davantage.

smolagents ou LangGraph : actions dynamiques ou contrôle d’un workflow persistant ?

LangGraph constitue un meilleur point de départ lorsque votre processus doit conserver son état, se mettre en pause et reprendre en passant par des états métier explicites. C’est un moteur d’orchestration de bas niveau pour les workflows avec état, qui prend en charge la persistance et l’intervention humaine. Il peut associer des étapes déterministes à des étapes pilotées par un modèle et ne nécessite pas LangChain. Présentation de LangGraph.

Prenez un workflow d’achat qui rassemble des éléments, attend la décision d’un responsable, puis reprend après approbation. Le problème central est de préserver le processus et de faire respecter la transition autorisée. Partez de LangGraph si ces exigences définissent le produit.

Sa contrepartie est la conception du workflow qui vous incombe : états, transitions, persistance et conséquences de la relance d’une étape. Cet effort se justifie pour le processus d’achat. Il peut alourdir inutilement un assistant de recherche au périmètre limité, qui lit des données, calcule une réponse, puis s’arrête.

Choisissez smolagents lorsque l’incertitude porte surtout sur les opérations Python qui permettront de résoudre la tâche. Choisissez LangGraph lorsqu’elle porte surtout sur la manière de faire progresser ce processus de façon sûre entre des états persistants. Il s’agit d’une recommandation de conception, pas d’une affirmation selon laquelle chaque framework serait limité à un seul type de travail.

OpenAI Agents SDK : passages de relais, contrôles et traces

L’OpenAI Agents SDK est un meilleur choix par défaut lorsque la coordination entre spécialistes et les contrôles opérationnels sont au cœur de l’application. Ses passages de relais, ou handoffs, transfèrent la prise en charge de la conversation à un autre agent ; son approche des agents utilisés comme outils permet à un agent coordinateur de garder la responsabilité de la réponse. Documentation sur l’orchestration.

Pour un assistant de support client, un spécialiste de la facturation qui reprend la conversation peut constituer une abstraction plus claire qu’un agent généraliste qui résout des problèmes en Python. Le traçage intégré enregistre les appels aux modèles, les appels d’outils, les passages de relais et les garde-fous. Ces garde-fous assurent des contrôles automatisés, tandis que les mécanismes de validation humaine suspendent les actions sensibles dans l’attente d’une décision. Traçage, garde-fous et validation.

La limite reste la politique de votre application : déterminer ce qui exige une approbation, implémenter correctement l’outil et gérer les travaux interrompus. Ces primitives ne définissent pas cette politique à votre place. Le SDK documente aussi des architectures d’agents en sandbox ; l’exécution de code n’est donc pas l’apanage de smolagents.

Préférez smolagents si vous avez besoin de composer des actions en Python et qu’une petite boucle suffit. Choisissez l’Agents SDK si ses primitives de coordination et de validation correspondent à l’application que vous construisez. La seule « légèreté » ne permet pas de trancher.

Pour élargir votre sélection, consultez le comparatif des frameworks d’agents IA. Si vous cherchez une application d’agent à installer plutôt qu’une bibliothèque sur laquelle construire, commencez par le guide des agents IA open source.

Que surestime-t-on chez les agents qui exécutent du code ?

Un petit framework ne rend pas prévisible une tâche qui ne l’est pas. L’expressivité de Python est utile, mais elle ne garantit pas que le modèle a sélectionné les bons enregistrements, interprété correctement une unité ou respecté une règle métier.

Ne faites pas de la composition d’opérations une promesse universelle de rapidité. Regrouper des opérations peut modifier le déroulement d’une exécution ; le résultat dépend toujours du modèle, de la tâche, du comportement des outils et de l’environnement d’exécution. Mesurez votre propre cas d’usage avant de choisir sur des critères de performance.

Une limite concrète mérite aussi votre attention : dans l’API actuelle des agents, max_steps vaut 20 par défaut. Ce paramètre borne les étapes de l’agent, pas les ressources consommées par une action Python individuelle. L’API expose également des callbacks, des agents gérés et des contrôles de la réponse finale : minimalisme ne signifie donc pas absence de contrôles. Référence des agents.

En pratique, fixez séparément les limites de durée d’exécution et de ressources. Un plafond d’étapes ne remplace pas une politique de sandbox, et une sandbox ne garantit pas un résultat correct.

Par quoi commencer la semaine prochaine ?

Commencez par une tâche délimitée, en lecture seule, dont vous pouvez vérifier la réponse indépendamment. Pour évaluer smolagents, un développeur Python peut utiliser un export d’inventaire dont les données sensibles ont été retirées et un outil de consultation au périmètre restreint, puis comparer les anomalies signalées par l’agent à des exemples connus.

Notez si l’agent a sélectionné les bons enregistrements, utilisé les outils correctement, repris après les échecs prévus et respecté vos limites d’exécution. Conservez une solution déterministe comme référence. Si la tâche suit toujours le même chemin, écrivez ce chemin en code classique ; Hugging Face recommande lui-même de privilégier les fonctions déterministes chaque fois que possible. Bien construire ses agents.

Adoptez CodeAgent lorsque la composition dynamique de Python justifie la complexité qu’elle introduit. Utilisez ToolCallingAgent lorsqu’un ensemble d’outils prédéfinis suffit. Reportez la migration si votre workflow actuel répond déjà à ses exigences. Réexaminez le choix du framework lorsque des approbations dont l’état doit persister ou des passages de relais entre spécialistes deviennent centraux.

Installation et compatibilité : les questions courantes

Comment installer smolagents avec pip ?

Installez la bibliothèque de base avec pip install smolagents. Ajoutez les dépendances optionnelles nécessaires à vos outils, à vos modèles ou à votre environnement d’exécution. L’exemple de cet article utilise smolagents[docker].

Que faut-il savoir sur HfApiModel dans smolagents ?

Pour du nouveau code, suivez l’interface InferenceClientModel présentée dans la documentation actuelle. Vérifiez les anciens exemples à l’aide de la référence des modèles en ligne avant d’en copier les imports.

Comment utiliser smolagents avec Docker ?

Installez et démarrez Docker, installez la dépendance optionnelle Docker, puis sélectionnez executor_type="docker". Configurez le périmètre d’exécution en fonction de votre charge de travail ; ce réglage ne constitue pas à lui seul une politique de sécurité complète.

Recevez des conseils pratiques pour construire avec l’IA dans la newsletter.