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. Cette page s'adresse au responsable technique, produit ou SI qui doit transformer ce prototype en logiciel qu'une équipe peut relire, tester, livrer et auditer. Elle permet de décider quelle forme donner au code d'un agent d'IA en Python : un projet rangé, un état explicite, des outils déterministes et des tests qui arrêtent une régression.

Le cadrage, le niveau d'autonomie et la spécification se décident en amont ; le code qui suit en est l'implémentation.

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 décider et agir dans un environnement donné, souvent via des outils externes, base de données, recherche web ou interface de programmation, là où un agent conversationnel reste cantonné au texte. L'autonomie qu'on lui accorde se règle selon les quatre niveaux de droits d'un agent d'IA, de la lecture seule à l'autonomie encadrée : cette grille n'est pas redéfinie ici, le code la met en œuvre.

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, 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 et 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 : le modèle prend la partie probabiliste, planification et reformulation, et tout le reste, données, calculs, exports, reste vérifiable. Une règle qui doit toujours donner le même résultat 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 : il collecte et livre une synthèse structurée avec ses sources.
• L'agent d'analyse : il 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 : il enchaîne brief, rédaction, contrôles qualité et livraison ; son cœur est le pipeline de contrôles, non le modèle.

Ces trois formes relèvent d'une même catégorie, l'agent orienté tâches utilisant des outils, parmi les sept familles d'agents décrites dans le pilier ; elles ne diffèrent que par les outils branchés et les preuves attendues.

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é se décide dès les premiers dossiers, avec une règle : rien de ce qui change d'un environnement à l'autre, seuil, identifiant, chemin, quota, ne vit dans le code qui décide.

Quatre dossiers, et ce que chacun contient

L'arborescence minimale compte quatre répertoires, et ce n'est pas une préférence de style : chacun correspond à 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 le code métier des connecteurs : cette frontière permet de tester la logique sans réseau, un jeu de données figé remplaçant le connecteur. Un agent dont la boucle ne s'exécute pas 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

Un identifiant écrit en dur ressemble à une variable ordinaire, survit aux relectures et finit dans l'historique du gestionnaire de versions, d'où il ne s'efface pas vraiment. Trois règles évitent ce genre de fuite.

• Les secrets : dans un gestionnaire dédié, jamais dans le dépôt, séparés par environnement.
• La configuration : chargée au démarrage, avec un échec immédiat quand une valeur obligatoire manque.
• Les jeux d'essai : dans le dépôt, donc 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 : ce qu'un agent d'IA dans VS Code a le droit de toucher se décide au même moment, et ne se confond pas avec l'agent que vous écrivez.

É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. Le piège classique est 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 les quatre temps, plan, action, observation, décision, et chacun produit un objet inspectable : vous savez où en est l'agent sans relire ses sorties. En Python, cela donne un état sérialisable, un identifiant d'opération unique par action contre les doublons au rejeu, des assertions sur des valeurs observées plutôt qu'un avis du modèle, et un contrat d'échange versionné qui refuse toute sortie hors schéma. La logique de la boucle est détaillée dans le workflow d'un agent d'IA.

Les limites qui empêchent 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 et des règles d'arrêt qui s'appliquent sans arbitrage.

• Supervision humaine : validation obligatoire avant toute écriture, publication, suppression, envoi ou mise à jour d'un système tiers, soit le niveau d'écriture contrôlée du pilier.
• 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 limites se vérifient dans du code, pas dans une intention. Un critère d'arrêt fondé sur la confiance que le modèle s'accorde n'en est pas un : écrivez-le comme une condition sur une valeur observable, preuves collectées, écart entre deux sources, champ 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 : tout ce qui touche à la vérité, données, calculs, extraction, mise en forme, passe par des fonctions déterministes, 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, et quatre propriétés le définissent.

• Une responsabilité : un outil fait une chose, et son nom dit laquelle.
• Des paramètres typés : le domaine de chaque entrée est déclaré, pas deviné.
• Une sortie validée par un schéma : ce qui en sort est conforme avant d'être transmis.
• Une erreur explicite : quand quelque chose manque, l'outil échoue, il ne complète pas.

L'écosystème Python couvre l'essentiel sans rien demander au modèle : la bibliothèque standard ou les pilotes de votre moteur pour l'accès aux données, une bibliothèque de calcul tabulaire (pandas, par exemple) pour l'analyse, une bibliothèque de graphiques et un moteur de gabarits (Jinja, par exemple) pour la restitution. 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, trois règles se posent dans l'outil lui-même, pas dans le prompt qui l'appelle.

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, des mois après l'exécution, à trois questions : qu'a-t-il fait, avec quelles données, et sur quelle règle a-t-il décidé ? Ces réponses 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 : les actions montrent ce qui s'est passé, les décisions montrent pourquoi. Le critère de suffisance : rejouer une exécution complète à partir des seuls journaux. Ce qu'ils deviennent une fois l'agent branché sur les systèmes de l'entreprise relève de l'intégration d'un agent d'IA.

Framework ou implémentation maison

Une bibliothèque 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 fait perdre le chemin plan, action, preuve, décision, devient impossible à déboguer, à tester et à sécuriser.

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

Cinq critères tranchent, 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 bibliothèque 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. Trois situations couvrent la quasi-totalité des cas.

• Récupération documentaire, routage d'outils, pipelines modulaires : une bibliothèque d'assemblage se justifie, elle évite de réécrire une plomberie connue.
• Problème découpé 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.
• Trois outils et deux règles : une implémentation simple sera plus robuste et plus facile à prouver qu'une dépendance de plus.

Dans le cas des rôles, le bon pattern sépare un agent d'analyse, qui manipule données et calculs, et un agent d'édition, avec un validateur qui bloque toute affirmation sans preuve. Le troisième cas est le plus fréquent et le plus souvent écarté à tort : coder maison gagne sur la lisibilité, le contrôle et la preuve, et 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 ». L'équipe qui recevra l'agent 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

Les trois volets de la recette, jeux de cas, critères d'acceptation et non-régression, sont ceux de la méthode pour créer un agent d'IA ; ici, ils se traduisent en familles de tests exécutées à chaque changement de prompt, de règle ou de connecteur. Le volet le plus discriminant reste la non-régression : un agent dont la décision varie sur une entrée identique n'est pas prêt. Le tableau donne, pour chaque famille, ce qui bloque la livraison.

Empaquetage, environnements et reproductibilité

La reproductibilité est une obligation, 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 la garantissent.

• Isoler l'exécution : un environnement virtuel dédié au projet, et rien d'installé en dehors.
• Figer les dépendances : un lock file (pip, Poetry ou uv), dépendances indirectes comprises.
• Externaliser la configuration : 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 échoue explicitement si une variable obligatoire manque. Dix lignes transforment 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. Trois leviers le tiennent.

• Réduire le contexte transmis : plafonner sa taille et mettre en cache les récupérations.
• Limiter les itérations : fixer des budgets de nombre d'appels et de durée, posés dans la configuration.
• Préférer un outil déterministe à une nouvelle question au modèle : une vérification écrite en code donne une réponse stable, là où reformuler coûte un appel de plus sans rien garantir.

Le troisième levier est le plus rentable et le moins appliqué. Mesurez le coût par exécution et coupez les boucles au-delà d'un seuil journalisé : c'est la seule manière de savoir si un agent coûte plus cher parce qu'il traite plus, ou parce qu'il tourne en rond.

Continuez votre lecture

Selon l'étape où vous en êtes, trois articles prolongent celui-ci.

• Vos tests passent et il faut 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 bibliothèque 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.
• 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.

Et si l'enjeu n'est pas d'écrire le code vous-même mais d'obtenir un agent conçu sur vos données, vos règles et vos preuves, c'est le cadre d'une IA personnalisée pour votre entreprise.

FAQ sur les agents d'IA en Python

Comment créer un agent IA avec Python ?

Un agent d'IA en Python se crée en écrivant d'abord une boucle contrôlée : état sérialisable, plan court, exécution par des outils déterministes, puis vérification et décision. Le projet se range en quatre dossiers, configuration, connecteurs, agent et tests, avant la première fonction. Le modèle ne prend que la partie probabiliste ; données, calculs et exports restent vérifiables.

Quels frameworks utiliser ?

Le framework se choisit selon la forme du problème, pas selon la notoriété d'un outil. Une bibliothèque d'assemblage se justifie pour la récupération documentaire, le routage d'outils ou les pipelines modulaires ; une structure orientée rôles, quand le travail se découpe en recherche, analyse, rédaction et contrôle. Pour trois outils et deux règles, une implémentation maison est 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 : bibliothèque standard ou pilotes du moteur pour les données, bibliothèque de calcul tabulaire pour l'analyse, moteur de gabarits pour la restitution. Le critère 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, tandis qu'un agent maintient un état, choisit ses actions selon un objectif, s'appuie sur des outils externes et vérifie ses résultats avant de décider de la suite. Le critère de bascule : si votre code produit un livrable ou déclenche une action, et qu'il s'auto-évalue, c'est déjà un agent.

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

Les hallucinations s'évitent par une règle unique : aucune affirmation sans preuve. Les outils extraient et calculent à la place du modèle, le format de sortie impose citations, dates et extraits, et chaque sortie est validée contre un schéma avant l'étape suivante. En l'absence de source, l'agent réclame la donnée manquante au lieu de compléter.

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

Une mémoire persistante devient nécessaire quand l'agent suit un dossier sur plusieurs exécutions : historique, décisions prises, exceptions accordées. Une récupération documentaire s'impose quand la qualité dépend d'informations précises et localisées, procédures internes ou documentation produit, et qu'il faut citer ses sources. Dans les deux cas, la charge de conformité augmente.

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

Le moindre privilège s'applique d'abord : lecture seule par défaut et fonctions d'écriture déclarées comme telles. Une validation humaine précède les actions destructrices, avec des critères d'arrêt stricts sur le budget d'actions, le temps, le coût et les preuves. Chaque opération est idempotente, et le journal conserve qui a demandé quoi, ce qui a été fait et sur quelle règle.

Quels tests automatiser pour fiabiliser un agent avant production ?

Cinq familles de tests s'automatisent avant production : tests unitaires des outils, tests d'intégration des contrats d'échange, sorties de référence à tolérance contrôlée, tests de sécurité sur les permissions et les secrets, et scénarios métier validant des critères d'acceptation concrets. La non-régression, même entrée et même décision, complète l'ensemble ; un refus correct compte comme une réussite.