Aller au contenu

ADR-026 — Refactoring progressif agent par agent + adoption LangChain/LangGraph
Statut Accepted
Date 26/06/2026 (call archi Denis × Dimitri × Romain)
Décideurs Dimitri Hertz, Romain BAZIL, Denis Mludek (CTO)
Origine Synchro archi 26/06 §5 + DMO 29/06 §4

Contexte

Le microservice IA Python a été construit avec un DAG maison (graphe d'orchestration sur mesure) pour chaîner les agents. Le choix initial visait à limiter les couches d'abstraction et à rester proche du code brut, avec un workflow séquentiel qui ne semblait pas justifier une surcouche. À l'époque, LangChain/LangGraph (V0) étaient jugés lourds et instables.

Conséquence aujourd'hui : le projet est difficile à débugger (connaître l'ordre d'exécution du graphe oblige à consulter une doc externe), et les derniers jours ont vu des bugs longs à résoudre (variables d'environnement, comportements inexpliqués). Dimitri reprend l'ownership technique de la partie IA et pose le refactoring comme premier de ses 5 axes structurants.

Décision

Refactoring  →  progressif, AGENT PAR AGENT (pas de tunnel de refonte big-bang), priorisé par impact
Mix effort   →  ~70 % features / 30 % refacto diluée dans chaque livraison (confirmé 21/07)
Orchestration →  migration du DAG maison vers LangChain / LangGraph (V1)
Cible        →  clean architecture, lisible par un humain ET par un LLM
Double gain  →  structure clean + amélioration de perf de l'agent (« une pierre deux coups »)
Cohabitation →  V1 (existant) et V2 (refactorisé) peuvent coexister, pas besoin de tout passer V2 d'un coup

Rationale

  • Débuggabilité : le DAG maison est difficile à visualiser/débugger ; LangGraph donne nativement la structure et l'ordre d'exécution.
  • La donne a changé depuis le choix initial : LangChain/LangGraph V1 ont fait un gros travail de refonte (vs V0 catastrophique), et les LLM les comprennent désormais — les deux arguments d'origine (instabilité, incompréhension LLM) ne tiennent plus.
  • Standard de recrutement : ce sont les deux plus grosses libs connues de tous les profils AI engineering ; une structure connue (« comme NestJS ») facilite l'onboarding et le recrutement (cf. ADR-024).
  • Progressif > big-bang : chaque agent refactorisé apporte un livrable + un gain de perf mesurable, sans le risque d'un tunnel de refonte ; cohérent avec « construire le système le plus simple possible, complexifier seulement si nécessaire ».
  • Anti context-rot : assainir une base vibe-codée évite d'atteindre le point où l'IA n'arrive plus à débugger (cf. épisode récent des multiples méthodes d'authentification).

Conséquences

Ce qui change

  1. La couche d'orchestration migre progressivement du DAG maison vers LangGraph.
  2. Chaque agent V2 respecte une clean architecture (langage fonctionnel clair, séparation des responsabilités).
  3. Le wrapper LangChain sert aussi d'abstraction provider LLM (switch de modèle facile — souveraineté + résilience, cf. ADR-024).

Ce qu'il faut faire

  • Prioriser par impact : premier chantier identifié = la présentation générale du projet (beaucoup de feedback négatif, utile en transverse).
  • Refaire chaque agent en LangGraph + clean archi en visant un gain de perf à chaque passe, pas seulement du structurel.
  • Clarifier et aligner le schéma de données Python (quasi inexistant aujourd'hui) et reprendre la gestion des migrations côté Python (cf. ADR-025).

Ce qu'il faut éviter

  • Tunnel de refonte de bout en bout (big-bang) : pas de livrable intermédiaire, trop risqué.
  • Forcer tous les agents en V2 d'un coup : la cohabitation V1/V2 est assumée.
  • Re-coder maison ce qu'une lib standard mature fait désormais bien.

Alternatives écartées

  • Garder le DAG maison : proche du code brut, mais difficile à débugger/visualiser/onboarder, pénalise maintenance et recrutement. Les raisons du choix initial (V0 instable, mal compris des LLM) ne sont plus valables.
  • Refonte big-bang complète : pas de livrable intermédiaire, risque élevé de régression, contraire au principe « le plus simple possible, complexifier si nécessaire ».

Verbatims

« Aujourd'hui [le DAG maison] est difficile à déboguer. Ne serait-ce que pour avoir l'ordre d'exécution du graph, tu dois aller consulter une doc. » — Dimitri

« Les premières versions de LangGraph n'étaient pas terribles. Ils ont fait un gros travail avec la V1. À l'époque c'était vrai, aujourd'hui ça l'est plus. » — Dimitri

« Faire un refactoring progressif agent par agent (…) autant faire d'une pierre deux coups, qu'il y ait aussi un gain et qu'on soit pas simplement sur du structurel. » — Dimitri (intro 26/06)

« On avait comparé versus LangGraph et fait le choix de manière éclairée vu la façon dont on voulait build. Mais la donne a changé maintenant qu'on investit avec de la ressource technique. » — Romain

« Je préfère faire une refacto graduelle. […] 70 % de fonctionnalités, 30 % de refacto […] pour ne pas vous bloquer complètement tout en assainissant le code. » — Dimitri (synchro 21/07)

Voir aussi

Sources