Créer un agent d'IA en Python : structurer, tester, livrer

Vous avez un fichier Python qui appelle un modèle, qui fonctionne une fois sur trois, et que personne d'autre que vous ne sait relire. La question n'est plus de savoir ce qu'est un agent : c'est de savoir quelle forme doit prendre votre code pour qu'on puisse le relire, le tester, le livrer et l'auditer. Écrire un agent d'IA en Python ne se joue pas sur la finesse d'un prompt, mais sur quatre choses ordinaires : un projet rangé, un état explicite, des outils déterministes et des tests qui arrêtent une régression. Pour ce qui se décide en amont — cadrage, niveau d'autonomie, spécification, protocole de décision —, savoir créer un agent d'IA donne le cadre que le code qui suit implémente.

Du script à l'agent : ce qui change dans votre code

Un agent d'IA n'est pas un « chat » amélioré. C'est un système conçu pour prendre des décisions et réaliser des actions autonomes dans un environnement donné, souvent via des outils externes — base de données, recherche web, interface de programmation —, là où un agent conversationnel reste cantonné à la génération de texte sans action réelle. La différence ne tient pas à la qualité du texte produit : elle tient au fait d'agir, donc à l'obligation de prouver ce qui a été fait.

Votre critère pratique est simple : si votre code fait autre chose que renvoyer une réponse — créer un rapport, lancer une requête, produire un livrable, déclencher une action — et qu'il s'auto-évalue, vous êtes déjà dans une logique d'agent. Un script exécute une suite d'instructions. Un agent maintient un état, choisit ses actions selon un objectif, s'appuie sur des outils externes, puis vérifie ses résultats avant de décider de la suite.

Avant d'écrire la moindre ligne, posez un vocabulaire commun. En production, la confusion entre modèle, outil, agent et orchestration se paie en bugs, en dérives et en factures.

• Le modèle de langage : il génère, classe, reformule. C'est la seule brique que vous assumez comme probabiliste.
• L'outil : il exécute une action déterministe, vérifiable et rejouable à l'identique.
• L'agent : il planifie, choisit les outils, contrôle le résultat obtenu et décide de la suite.
• L'orchestration : elle cadence, déclenche et supervise les exécutions.

Ce découpage porte toute la thèse de cet article : branchez un modèle de langage pour la partie probabiliste — planification, reformulation —, tout le reste restant vérifiable : données, calculs, exports. Si une règle doit toujours donner le même résultat, elle s'écrit en Python, pas dans un prompt.

Trois formes reviennent presque toujours, avec les mêmes briques : l'agent de recherche et de synthèse, qui collecte et livre une synthèse structurée avec ses sources ; l'agent d'analyse, qui transforme des exports bruts en décisions priorisées sans deviner — il calcule, puis explique, et conserve la traçabilité ; l'agent de production contrôlée, qui enchaîne brief, rédaction, contrôles qualité et livraison, son cœur étant le pipeline de contrôles et non le modèle.

Structurer le projet avant d'écrire la boucle

Un agent qu'on ne peut pas tester ne se livre pas : il se démontre, ce qui n'est pas la même chose. La testabilité ne s'ajoute pas après coup, elle se décide au moment où vous créez les premiers dossiers. La règle qui gouverne le reste tient en une ligne : rien de ce qui change d'un environnement à l'autre — seuil, identifiant, chemin, quota — ne doit se trouver dans le code qui décide.

Quatre dossiers, et ce que chacun contient

L'arborescence minimale tient en quatre répertoires. Ce n'est pas une préférence de style : chacun correspond à une catégorie de changement, donc à une raison distincte de modifier le projet. Un fichier qui pourrait tomber dans deux d'entre eux signale une responsabilité mal découpée.

• Configuration : environnements, seuils, règles métier, correspondances. Ce qui se modifie sans relivrer le code.
• Connecteurs : les clients d'interfaces externes, avec les quotas, les délais et les erreurs de chaque fournisseur.
• Agent : le planificateur, l'exécuteur, les validateurs et la politique d'action. C'est le seul dossier où se prennent des décisions.
• Tests : cas fixes, non-régressions et simulations d'erreurs des fournisseurs externes.

Séparez clairement le code métier des connecteurs : c'est cette frontière qui permet de tester la logique de l'agent sans réseau, en substituant un connecteur par un jeu de données figé. Un agent dont on ne peut pas exécuter la boucle hors ligne n'a pas de tests : il a des appels réels que quelqu'un relance à la main.

Ce qui ne vit pas dans le dépôt : secrets, configuration, jeux d'essai

Externalisez les secrets dans un gestionnaire dédié, jamais dans le dépôt, et séparez-les par environnement. Un identifiant écrit en dur survit aux relectures — il ressemble à une variable ordinaire — et finit dans l'historique du gestionnaire de versions, d'où il ne s'efface pas vraiment. La configuration suit la même logique : chargée au démarrage, avec un échec immédiat quand une valeur obligatoire manque.

Les jeux d'essai, eux, vivent dans le dépôt : c'est pour cela qu'ils doivent être synthétiques. Un export réel embarqué « pour tester » fait entrer des données clients dans un projet cloné sur plusieurs postes. Si votre éditeur héberge lui-même un agent qui lit ce dépôt, les mêmes règles valent pour lui, avec la question de ce qui part dans son contexte : ce qu'un agent d'IA dans VS Code a le droit de toucher se pose au même moment, et ne se confond pas avec l'agent que vous écrivez ici.

Écrire la boucle agentique

Un agent solide ressemble moins à une démonstration qu'à une boucle contrôlée : état explicite, actions déterministes, preuves, puis décision. L'objectif est double — rendre les erreurs visibles tôt, et les actions auditables après coup. Le piège classique porte un nom : l'enchaînement modèle, outil, modèle qui ne s'arrête jamais, parce qu'aucune étape ne sait dire si elle a progressé. On en sort par un état structuré et des transitions explicites, pas par une consigne de plus dans le prompt.

Les quatre temps : plan, action, observation, décision

Chaque itération traverse quatre temps, et chacun produit un objet inspectable. C'est ce qui distingue une boucle d'une suite d'appels : à la fin de chaque tour, vous savez où en est l'agent sans relire ses sorties.

• Plan : sélectionner une seule action prioritaire candidate et produire une sortie structurée stricte, avec ses hypothèses et ses critères de succès.
• Action : exécuter via un connecteur, avec un identifiant d'opération unique, pour qu'un rejeu ne produise pas de doublon.
• Observation : collecter les métriques et l'état, avant et après, puis vérifier des assertions plutôt que demander au modèle si tout va bien.
• Décision : continuer, corriger, escalader vers un humain, ou arrêter parce qu'un seuil est atteint.

Le pattern qui rend cela exploitable : modéliser l'état dans un objet sérialisable, puis écrire un utilitaire qui rejoue une exécution à partir des journaux. Le format d'échange entre le planificateur, les connecteurs et les validateurs se traite comme un contrat versionné : toute entrée ou sortie non conforme au schéma est refusée avant d'aller plus loin.

Ce qui empêche la boucle de tourner à vide

Un agent en Python devient dangereux quand il agit sans limite. Encadrez son autonomie comme un budget, avec des plafonds écrits dans la configuration : nombre d'actions, coût, durée, et règles d'arrêt qui s'appliquent sans arbitrage.

• Supervision humaine : validation obligatoire avant toute écriture — publication, suppression, envoi, mise à jour d'un système tiers.
• Critères d'arrêt : pas de preuve, pas d'action ; confiance insuffisante, escalade ; trois itérations sans progression mesurée, arrêt.
• Budget d'actions : limiter les appels réseau, les boucles de planification et la taille du contexte transmis.

Ces trois garde-fous se vérifient dans du code, pas dans une intention. Un critère d'arrêt qui dépend de l'appréciation du modèle sur sa propre confiance n'en est pas un : écrivez-le comme une condition sur une valeur observable — preuves collectées, écart entre deux sources, champ obligatoire absent —, et l'arrêt devient reproductible.

Les outils : rendre déterministe ce qui peut l'être

Vos outils doivent être plus fiables que votre modèle. Autrement dit : tout ce qui touche à la vérité — données, calculs, extraction, mise en forme — passe par des fonctions déterministes, jamais par une génération libre. C'est le seul moyen d'obtenir deux fois le même résultat sur la même entrée. Un outil se conçoit comme une fonction étroite : une responsabilité, des paramètres typés, une sortie validée par un schéma, une erreur explicite quand quelque chose manque.

L'écosystème Python couvre l'essentiel sans rien demander au modèle. L'accès aux données passe par les bibliothèques standard ou les pilotes de votre moteur, l'analyse par les bibliothèques de calcul tabulaire et numérique, la restitution par une bibliothèque de graphiques et un moteur de gabarits qui sépare les données de leur présentation. Ce dernier point n'est pas cosmétique : un rapport dont la mise en forme est générée à chaque exécution ne se compare pas d'une version à l'autre, donc ne se teste pas.

Avant d'autoriser une action, posez trois garde-fous dans l'outil lui-même. La lecture seule par défaut : toute fonction qui écrit est déclarée comme telle et exige une autorisation explicite. La validation des entrées : un paramètre hors domaine fait échouer l'appel, il ne le fait pas dévier. L'idempotence : la même opération rejouée laisse le système dans le même état. Quand l'agent doit répondre ou décider à partir de documents internes, l'outil n'est plus un simple accès : le découpage du corpus, la stratégie de récupération et la citation des sources relèvent alors de l'agent d'IA avec RAG, et cette brique se conçoit pour elle-même.

Journaliser, tracer, versionner

En entreprise, un agent sans observabilité est inutilisable, quelle que soit la qualité de ses sorties. Vous devez pouvoir répondre à trois questions, des mois après l'exécution : qu'a-t-il fait, avec quelles données, et sur quelle règle a-t-il décidé ? Aucune de ces réponses ne se reconstitue de mémoire. Elles se préparent au moment où vous écrivez la boucle, et elles coûtent quelques lignes autour de chaque appel d'outil.

• Journaux structurés : action, entrée, sortie, durée, erreur, coût estimé — dans un format lisible par une machine.
• Traces : la chaîne d'appels et un identifiant de corrélation unique par exécution, propagé jusque dans les connecteurs.
• Prompts versionnés : empreinte, date, auteur, journal des modifications. Un prompt est du code, il se relit et se compare.
• Journal des décisions : arrêts, escalades, refus d'action, avec la règle qui les a déclenchés.

La quatrième ligne est celle qu'on oublie, et la seule qui intéresse un auditeur. Journaliser les actions montre ce qui s'est passé ; journaliser les décisions montre pourquoi. Sans versionnement des prompts et des règles, vous ne saurez pas dire ce qui a changé entre une exécution correcte la semaine dernière et une exécution ratée aujourd'hui — et vous passerez ce temps à modifier le prompt au hasard.

Un dernier critère dit si votre observabilité suffit : vous devez pouvoir rejouer une exécution complète à partir des seuls journaux, sans rouvrir les systèmes d'origine.

Framework ou implémentation maison

Une librairie d'assemblage doit accélérer sans masquer les décisions. Ce que vous payez le plus cher n'est ni le temps d'écriture ni la licence : c'est l'illisibilité. Une architecture « magique », qui empile les abstractions au point de vous faire perdre la lecture du chemin plan, action, preuve, décision, devient impossible à déboguer, à tester et à sécuriser. Le bon outil est celui que vous pouvez faire tourner, tester et auditer à l'échelle.

Les critères qui décident, et leurs signaux d'alerte

Cinq critères suffisent à trancher, et chacun se vérifie sur un cas réel plutôt que sur un exemple de documentation. Le tableau donne, pour chacun, le signal qui doit faire reculer et sa conséquence dans le code.

Quand une librairie d'assemblage aide, et quand elle coûte

La décision se prend sur la forme du problème, jamais sur la popularité d'un outil. Une librairie d'assemblage est à utiliser si vous faites de la récupération documentaire, du routage d'outils ou des pipelines modulaires. Elle est à éviter si votre besoin tient en trois outils et deux règles : une implémentation simple sera plus robuste et plus facile à prouver.

Un second cas la justifie : quand votre problème se décompose en rôles — recherche, analyse, rédaction, contrôle qualité —, une structure orientée rôles évite l'agent monolithe qui fait tout et devient impossible à fiabiliser. Le bon pattern sépare alors un agent d'analyse, qui manipule données et calculs, et un agent d'édition, avec un validateur qui bloque toute affirmation sans preuve.

Reste le cas le plus fréquent, écarté à tort. Si vous avez un périmètre clair — générer un rapport à partir d'exports, par exemple —, coder maison est souvent le meilleur choix : vous gagnez sur la lisibilité, le contrôle et la capacité à prouver ce que fait l'agent. Le coût d'une dépendance apparaît à la première montée de version qui casse une abstraction dont vous dépendiez sans le savoir.

Recetter avant de livrer

Testez comme un produit, pas comme un carnet de notes. La question n'est pas « est-ce que ça marche » — une démonstration ne montre que le chemin nominal —, mais « qu'est-ce qui se passe quand ça ne marche pas ». Le passage en conditions réelles se joue sur trois sujets : reproductibilité, non-régression et coût. C'est la partie qui intéresse l'équipe qui recevra l'agent : elle ne juge pas votre boucle, mais elle sait lire un critère d'acceptation et refuser une livraison qui ne l'atteint pas.

Jeux de cas, critères d'acceptation et non-régression

La recette tient en trois volets, rassemblés dans un document relu à chaque changement de prompt, de règle ou de connecteur. Les jeux de cas : cas normaux, cas sensibles, données manquantes, quotas atteints. Les critères d'acceptation : taux de sorties valides, taux d'escalade, taux d'actions refusées correctement. La non-régression : même entrée, même décision, dans un intervalle acceptable. Le dernier est le plus discriminant et le premier oublié : un agent dont la décision varie sur une entrée identique n'est pas prêt.

Packaging, environnements et reproductibilité

La reproductibilité est une exigence, pas une commodité : sans elle, aucun test ne prouve quoi que ce soit, puisque rien ne garantit que l'environnement d'exécution sera le même demain. Trois gestes suffisent. Isolez l'exécution dans un environnement virtuel dédié au projet. Figez les dépendances dans un fichier de verrouillage, dépendances indirectes comprises. Externalisez la configuration, de sorte qu'un même artefact tourne en développement, en recette et en production sans qu'une ligne de code change.

Ajoutez un contrôle d'installation minimal : un point d'entrée qui importe les bibliothèques clés, vérifie l'accès aux connecteurs en lecture seule et sort en erreur explicite si une variable obligatoire manque. Il coûte dix lignes et transforme un diagnostic d'une demi-journée en message lisible.

Latence, contexte et coût par exécution

Votre coût n'est pas seulement financier : c'est aussi la latence, qui décide de ce que vos utilisateurs accepteront d'attendre. La discipline tient en trois leviers : réduire le contexte transmis, limiter les itérations, et préférer un outil déterministe à une nouvelle question posée au modèle. Le dernier est le plus rentable et le moins appliqué : une vérification écrite en code donne une réponse stable, là où reformuler coûte un appel de plus sans rien garantir.

Fixez donc des budgets — nombre d'appels, taille de contexte, durée —, mettez en cache les récupérations, et remplacez les re-générations par des contrôles déterministes. Mesurez le coût par exécution et coupez les boucles au-delà d'un seuil défini, posé dans la configuration et journalisé quand il se déclenche : c'est la seule manière de savoir si un agent est devenu plus cher parce qu'il traite plus, ou parce qu'il tourne en rond.

FAQ sur les agents d'IA en Python

Comment créer un agent IA avec Python ?

Créez d'abord une boucle contrôlée : état explicite et sérialisable, plan court, exécution via des outils déterministes, puis vérification et décision. Rangez le projet en quatre dossiers — configuration, connecteurs, agent, tests — avant d'écrire la première fonction. Ensuite seulement, branchez un modèle de langage pour la partie probabiliste, planification et reformulation, tout le reste restant vérifiable : données, calculs, exports.

Quels frameworks utiliser ?

Choisissez selon la forme de votre problème, pas selon la notoriété d'un outil. Une librairie d'assemblage se justifie pour de la récupération documentaire, du routage d'outils ou des pipelines modulaires ; une structure orientée rôles se justifie quand le travail se découpe en recherche, analyse, rédaction et contrôle. Si votre besoin tient en trois outils et deux règles, une implémentation maison sera plus robuste et plus facile à auditer.

Quels sont les meilleurs outils ?

Les meilleurs outils sont ceux qui rendent l'agent déterministe là où il doit l'être : accès aux données par les bibliothèques standard ou les pilotes de votre moteur, analyse par les bibliothèques de calcul tabulaire et numérique, restitution par un moteur de gabarits séparant données et présentation. Le critère de sélection n'est pas la richesse fonctionnelle, mais la capacité à rejouer le même appel et à obtenir le même résultat.

Quelle est la différence entre un agent Python et un simple script ?

Un script exécute une suite d'instructions. Un agent en Python maintient un état, choisit ses actions en fonction d'un objectif, s'appuie sur des outils externes, et vérifie ses résultats avant de décider de la suite : continuer, corriger, escalader ou s'arrêter. Le critère de bascule est pratique : si votre code produit un livrable ou déclenche une action, et qu'il s'auto-évalue, vous êtes déjà dans une logique d'agent.

Comment éviter les hallucinations et imposer des sorties vérifiables ?

Imposez une règle unique : aucune affirmation sans preuve. Utilisez des outils pour extraire et calculer plutôt que de demander au modèle, et forcez un format de sortie contenant citations, dates et extraits. Validez chaque sortie contre un schéma avant de la transmettre à l'étape suivante. En l'absence de source, l'agent doit réclamer la donnée manquante plutôt que compléter : c'est un choix de performance, pas de prudence excessive.

Quand faut-il ajouter une mémoire persistante ou un RAG ?

Ajoutez une mémoire persistante quand l'agent doit suivre un dossier sur plusieurs exécutions : historique, décisions prises, exceptions accordées. Ajoutez une récupération documentaire quand la qualité dépend d'informations précises et localisées — procédures internes, documentation produit — et que vous devez citer vos sources plutôt que générer au mieux. Dans les deux cas, la charge de conformité augmente : cela ne se décide pas par confort.

Quels garde-fous mettre en place avant d'autoriser des actions (écriture, publication, suppression) ?

Appliquez le moindre privilège, avec une lecture seule par défaut et des fonctions d'écriture déclarées comme telles. Exigez une validation humaine sur les actions destructrices et des critères d'arrêt stricts : budget d'actions, temps, coût, preuves. Rendez chaque opération idempotente pour qu'un rejeu ne crée pas de doublon. Journalisez systématiquement qui a demandé quoi, ce que l'agent a fait, et sur quelle règle il l'a fait.

Comment journaliser et auditer un agent (prompts, décisions, actions) pour le débogage et la conformité ?

Journalisez dans un format structuré : entrées, sorties, empreinte de version du prompt, appels d'outils, erreurs, latence et identifiant d'exécution. Conservez aussi les décisions — arrêt, escalade, refus d'action — avec la règle déclenchée, et les artefacts produits. Le test de suffisance est simple : vous devez pouvoir rejouer une exécution complète à partir des seuls journaux, sans rouvrir les systèmes d'origine.

Comment dimensionner les coûts et limiter les itérations inutiles ?

Fixez des budgets — nombre d'appels, taille de contexte, durée —, mettez en cache les récupérations, et remplacez les re-générations par des contrôles déterministes. Mesurez le coût par exécution et coupez les boucles au-delà d'un seuil défini, journalisé quand il se déclenche. Le levier le plus rentable reste le remplacement d'une question posée au modèle par une vérification écrite en code : elle est plus rapide, moins chère et stable.

Quels tests automatiser pour fiabiliser un agent avant production ?

Automatisez les tests unitaires des outils, les tests d'intégration des contrats d'échange, et des sorties de référence avec une tolérance contrôlée. Ajoutez des tests de sécurité — permissions, secrets, chemins de fichiers — et des scénarios métier qui valident des critères d'acceptation concrets. Vérifiez enfin la non-régression : même entrée, même décision, dans un intervalle acceptable. Un refus correct est un résultat de test au même titre qu'une réussite.

Continuez votre lecture

• Votre projet tient et vos tests passent : il faut maintenant les rejouer à chaque modification, ou juger un projet d'agent qu'on vous propose — c'est le terrain de l'agent d'IA sur GitHub.
• Vous avez retenu une librairie et devez vérifier ce que sa licence autorise, notamment si l'agent part dans un produit : licences, souveraineté et charge d'exploitation se comparent sur l'agent d'IA open source.
• Vos outils doivent atteindre les systèmes réels de l'entreprise : comptes de service, permissions, sources autorisées et environnements séparés relèvent de l'intégration d'un agent d'IA.
• Vous ne voulez pas tout écrire et cherchez ce qui existe déjà : modèles, éditeurs et outils d'automatisation se comparent sur une plateforme d'agent d'IA.