Ingénierie de graphes pour des agents de codage IA : contexte, contrats et réparation

« L’ingénierie de graphes » suscite beaucoup d’attention ces derniers temps, et la plupart des explications se concentrent sur les graphes, les nœuds et les DAG. Ces éléments sont importants, mais ils ne répondent pas à la vraie question qui mérite d’être posée : pourquoi les agents de codage basés sur l’IA auraient-ils soudainement besoin d’ingénierie de graphes ?

Un développeur qui a passé des mois à utiliser des outils tels que Claude Code, puis Codex, a remarqué un schéma récurrent. La plupart des tâches de codage échouent non pas parce que le modèle ne sait pas écrire du code, mais parce que les workflows de longue durée perdent progressivement leur structure. Le contexte s’éloigne de la synchronisation, les exigences sont oubliées, les résultats deviennent difficiles à vérifier, et lorsque quelque chose ne fonctionne pas, la solution la plus simple est souvent de redémarrer toute la tâche.

Cette observation a conduit à la création d’un petit cadre de recherche appelé ContractGraph. Le compte rendu ci-dessous retrace ses idées, ce qui a fonctionné et ce qui a échoué. Il n’a pas été conçu pour concurrencer les cadres existants, ni pour être lié à un modèle particulier. L’objectif était plus restreint : un flux de travail pouvait-il être conçu de manière à ce que chaque étape dispose d’un objectif clair, d’un contrat bien défini et d’une méthode déterministe pour déterminer si l’étape est réellement terminée ?

Le résultat a été un graphe piloté par des contrats qui permettait de gérer un flux de travail de recherche à travers des tâches isolées, une validation explicite et des corrections ciblées, au lieu d’un seul prompt géant. La première implémentation visait les agents de recherche, mais les idées sous-jacentes s’appliquent tout aussi bien aux agents de codage, aux pipelines de documents, aux systèmes d’évaluation et à tout processus où plusieurs étapes pilotées par l’IA doivent produire des résultats vérifiables. Gardez à l’esprit qu’il s’agit d’une expérience menée par un praticien, donc les conclusions proviennent de l’expérience plutôt que de benchmarks mesurés.

Que signifie l’ingénierie de graphe

L’ingénierie de graphe consiste à diviser un flux de travail d’IA complexe en petites unités d’exécution et à les relier par des règles explicites. Un système conçu selon cette approche combine généralement plusieurs unités d’exécution, des routages explicites, un état partagé, des mécanismes de vérification et une coordination fiable.

Une seule responsabilité par nœud. Les arêtes déterminent l’étape suivante. L’état partagé à travers le flux de travail transmet les informations, et une étape de vérification décide s’il faut continuer, réessayer, corriger ou arrêter.

Les deux questions à l’origine de la conception

Attendant à passer la majeure partie du temps sur les nœuds, les arêtes et le flux d’exécution, le développeur a découvert que ce n’étaient pas les parties les plus difficiles. Deux questions revenaient sans cesse.

Premièrement : quelles informations un agent IA devrait-il pouvoir considérer comme vraies ? Deuxièmement, une fois qu’il a terminé une tâche : comment savoir si le résultat répond réellement à la demande ?

Plus les workflows à long terme étaient testés, plus il devenait évident que ces questions prenaient le pas sur le graphe lui-même. Un agent qui part d’informations erronées, ou qui se retrouve sans moyen fiable de vérifier son travail, ne fait que transmettre des erreurs d’un nœud à l’autre. Ces deux questions sont devenues Contexte et Contrat. Le contexte définit ce qu’un agent est autorisé à croire, tandis que le contrat définit ce qu’il doit produire. Tout le reste du cadre repose sur ces deux concepts.

Contexte et contrats en tant que briques de construction

Le graphe n’était pas la partie la plus difficile. Le véritable défi résidait à s’assurer que chaque nœud partait des bonnes informations et produisait quelque chose de vérifiable avant que le workflow ne progresse.

Contexte. Les agents ne devraient pas voir tout ce qui se passe. Un nœud ne reçoit que les informations en lesquelles il peut avoir confiance, comme par exemple les exigences des utilisateurs, les contraintes du projet, les documents vérifiés ou les résultats acceptés provenant de nœuds antérieurs.

Contrat. Chaque nœud nécessite une définition claire de ce qu’il doit livrer. Lorsqu’un résultat ne répond pas aux exigences du contrat, le flux de travail ne peut pas simplement continuer sans s’arrêter. Il doit vérifier la sortie, corriger l’étape défaillante ou s’interrompre.

En termes simples, le contexte définit ce en quoi un agent peut avoir confiance, tandis que les contrats définissent ce qu’il doit livrer. Une fois ces deux limites clairement établies, il devient beaucoup plus facile de comprendre le graphe. Chaque nœud a une fonction précise, une source de vérité restreinte, une sortie mesurable, ainsi qu’un mécanisme déterministe avant le début de l’étape suivante.

De l’idée au graphe exécutable

Avec le contexte et les contrats séparés, la question suivante est de savoir comment ils deviennent un flux de travail exécutable. L’objectif n’était pas d’imprimer un graphe distinct pour la recherche, la programmation ou la génération de documents. Le flux de travail devrait plutôt être compilé dynamiquement à partir du problème lui-même, et non à partir de chemins prédéfinis. Deux étapes s’imposent d’abord.

La première étape consiste à construire le contexte. Tous les fichiers ou documents ne méritent pas une confiance égale, c’est pourquoi le flux de travail assemble un contexte canonique : une source de vérité validée sur laquelle tous les nœuds peuvent s’appuyer. Ses matières premières varient en fonction de la tâche, telles que des documents de projet, des exigences des utilisateurs, du code, des documents de conception ou d’autres données jugées fiables.

Le deuxième élément permet de créer le contrat. Au lieu de décrire la tâche uniquement en prose, il génère un contrat structuré indiquant ce que chaque étape doit produire, comment les nœuds dépendent les uns des autres et ce qui doit être validé avant que l’exécution ne puisse continuer.

Lorsque ces deux éléments sont en place, le flux de travail est compilé. Cette étape d’initialisation ne fait rien ; son rôle est de planifier. Elle produit le graphe d’exécution, un ensemble de contexte ciblé pour chaque nœud, des manifestes réutilisables et des compétences partagées, ainsi qu’un ordre d’exécution déterminé à partir des contrats, sans séquence fixe à l’avance.

L’exécution devient alors simple. Un nœud reçoit uniquement son contexte ciblé, effectue le travail qui lui a été assigné, passe par une validation déterministe, enregistre le résultat accepté et transmet le contrôle à l’étape suivante. Si la validation échoue, seul le nœud concerné est corrigé avant que l’exécution ne reprenne, de sorte que rien n’est à recommencer depuis zéro.

La structure du graphe provient donc du contexte et des contrats fournis au début, et non d’une implémentation fixe. Le même pipeline de compilation peut assembler des workflows pour la recherche, la programmation, la documentation ou tout autre domaine, sans modifier le temps d’exécution.

Le tester sur des modèles plus grands et plus petits

Concevoir un framework n’est que la moitié du travail. La question plus difficile est de savoir si l’architecture tient le choc lorsque le workflow devient suffisamment complexe pour révéler ses faiblesses.

Les premiers essais ont utilisé un workflow bien plus volumineux exécuté dans Claude Code, avec des nœuds d’exécution générés dynamiquement, des étapes de planification imbriquées et de longues tâches de recherche. La qualité était excellente, mais l’achèvement du workflow nécessitait une grande quantité de calculs du modèle.

Cela a soulevé une question supplémentaire : cette même architecture de graphe pourrait-elle encore produire des workflows fiables avec un modèle bien plus petit et moins coûteux ? Une deuxième expérience a utilisé un workflow de génération de plans d’étude, exécuté via OpenCode avec Big Pickle plutôt qu’avec un modèle de pointe. Les mécanismes sont restés les mêmes : le workflow était compilé dynamiquement, des nœuds spécialisés étaient générés, chaque étape était validée de manière déterministe, les pannes étaient corrigées le cas échéant, et le résultat final sortait du même pipeline.

L’objectif n’était pas de comparer les modèles ou de désigner un gagnant. Il s’agissait de voir dans quelle mesure la fiabilité provenait de l’architecture d’exécution plutôt que des capacités intrinsèques du modèle. La découverte surprenante a été que les plus gros problèmes n’étaient pas du tout des pannes de modèle, mais des pannes de workflow, et c’est là que l’ingénierie de graphe est devenue intéressante.

Où cela a échoué

L’expérience n’a pas montré que l’ingénierie de graphe empêchait les pannes. Elle a montré que l’ingénierie de graphe rendait les pannes visibles.

Pendant ce processus, toutes sortes de problèmes sont survenus : métadonnées incomplètes, preuves manquantes, références non résolues, contenu dupliqué, états de cycle de vie invalides, informations de suivi erronées, et même des problèmes d’encodage simples. Le graphe n’en était la cause à aucun de ces échecs. Ce sont les pannes que l’on pourrait attendre de workflows d’IA à long terme.

Ce qui a changé, c’est que chaque panne avait une localisation précise. Au lieu de considérer toute l’exécution comme une seule tentative échouée, il devenait possible de trouver le nœud spécifique qui avait violé ses contraintes, de réparer uniquement ce nœud, de réexécuter une validation déterministe, puis de reprendre à partir de là. Le reste du workflow restait intact, car chaque étape réussie avait déjà été vérifiée et enregistrée.

Cela a changé la façon dont le développeur percevait cette technique. Ce n’était pas un moyen de rendre les modèles plus intelligents, mais plutôt un moyen de rendre les échecs locaux, observables et réparables. Le graphe ne supprimait pas les erreurs, mais il attribuait à chacune d’elles une adresse.

Pourquoi la validation doit être déterministe

Un modèle peut affirmer avec une certitude absolue qu’une tâche est terminée, mais cela ne signifie pas pour autant qu’elle l’est réellement. Les modèles de langage raisonnent, résument et prennent des décisions de manière très efficace, mais ils ne sont pas des juges fiables pour déterminer si un flux de travail a satisfait à ses propres exigences.

C’est pourquoi chaque nœud dans ContractGraph se termine par une vérification déterministe. Personne ne sollicite un second modèle pour obtenir un avis sur le résultat. Le flux de travail teste des conditions objectives : le schéma dispose-t-il de tous les champs nécessaires ? Les dépendances ont-elles été remplies ? Les artefacts requis sont-ils présents, et les références fonctionnent-elles ? Le nœud a-t-il transmis tout ce que son contrat promettait ? Il ne s’agit pas d’évaluations subjectives ; chacune est simplement vraie ou fausse.

Cette séparation s’est avérée être l’une des idées les plus précieuses du framework. Le modèle se concentre sur le raisonnement, tandis que la validation déterministe s’occupe de la vérification. Un modèle peut affirmer que son travail est terminé, mais seul un validateur déterministe peut prouver qu’un champ requis manque.

Pourquoi cet effort supplémentaire peut être récompensé

Même avant cette expérience, le développeur considérait les agents de codage basés sur l’IA comme une petite équipe et non comme un simple assistant. Il n’était pas inhabituel que Claude Code, Codex et OpenCode travaillent simultanément sur différentes parties d’un même répertoire.

Cela a créé un problème inattendu : les agents pouvaient avoir besoin de modifier les mêmes fichiers ou de s’appuyer sur la même implémentation, et sans coordination, l’un pouvait écraser le travail de l’autre ou invalider des hypothèses établies précédemment.

La solution était simple : chaque tâche avait un responsable. Si un agent était chargé d’une partie du code, les autres ne pouvaient pas modifier ces fichiers tant que le responsable ne le permettait pas. En ajoutant une étape de validation après chaque étape majeure, de nombreux conflits n’arrivaient jamais jusqu’au répertoire.

Le compromis était évident. Ce type de développement nécessite bien plus de ressources que de demander à un seul modèle de développer une fonctionnalité au cours d’une seule conversation, car chaque étape de validation, de tentative répétée, de correction et de coordination ajoute du travail. Pourtant, le résultat était différent. Au lieu de devoir corriger en boucle les dérives causées par des corrections antérieures, le flux de travail est devenu beaucoup plus prévisible, et les fonctionnalités développées de cette manière nécessitaient peu de retravaux, car chaque étape était vérifiée avant que la suivante ne commence.

La conception de graphes n’est pas quelque chose que chaque demande devrait utiliser, et pour de petites modifications, c’est purement une perte de temps. Pour des fonctionnalités plus importantes, des implémentations longues ou des travaux impliquant plusieurs agents, le coût supplémentaire permet d’obtenir quelque chose de plus précieux que des inférences bon marché : il procure de la confiance.

Quel est le véritable coût

Nul ne doit interpréter ceci comme une affirmation selon laquelle l’ingénierie de graphes constituerait une solution miracle. Préparer le contexte, générer des contrats, compiler le graphes, valider, réparer et agréger chaque élément entraîne des appels supplémentaires au modèle ainsi que des coûts en tokens. Par rapport à une simple demande, ce flux de travail est indéniablement plus coûteux.

Les premiers essais avec les modèles de pointe ont donné d’excellents résultats, mais ils consommaient beaucoup de ressources de calcul, ce qui a été l’une des principales raisons de tester des modèles plus petits et moins chers. La leçon à retenir est que l’ingénierie de graphes ne réduit pas la consommation en calcul : elle la réalloue délibérément. Au lieu d’utiliser les ressources de calcul pour corriger des dérives, redémarrer des flux de travail défaillants ou réparer sans cesse des erreurs ultérieures, le système les consacre à l’avance à la planification, à la vérification et à l’isolement des pannes.

Cela change l’objectif d’optimisation. L’ingénierie de graphes n’a pas pour but de produire l’exécution la moins chère, mais plutôt la plus prévisible. Une seule exécution d’OpenCode a consommé une grande quantité de tokens. Ce chiffre ne doit pas être interprété comme une preuve que cette approche est économique. Au contraire, il montre que l’ingénierie de graphes consacre délibérément plus de ressources informatiques afin d’assurer l’isolation des pannes, la traçabilité, la possibilité de reprendre l’exécution et une plus grande fiabilité. Le fait que ce soit un bon échange dépend entièrement du problème.

Quand c’est utile

L’ingénierie de graphes n’est pas nécessaire pour chaque flux de travail d’IA. Pour une requête SQL, une petite fonction ou quelques ajustements de l’interface utilisateur, un prompt bien rédigé suffit généralement, et l’ajout de contrats, de couches de validation et de graphes d’exécution ne ferait qu’ralentir les choses et les compliquer davantage.

Elle commence à être utile lorsque le coût de l’échec dépasse celui d’un calcul supplémentaire. Cela concerne les recherches de longue durée, le travail sur de grandes quantités de données, les workflows multi-agents, les systèmes sensibles à la sécurité, l’automatisation d’entreprise, ainsi que tout processus dont les résultats doivent être vérifiables et reproductibles. Plus un workflow comporte d’étapes, plus une coordination explicite s’avère nécessaire.

La leçon principale n’a rien à voir avec l’intelligence artificielle. Lorsqu’un workflow est complexe, sa structure le rend plus facile à suivre, à vérifier, à corriger et à étendre. Cette idée est encore loin d’être épuisée : l’exécution tenant compte des dépendances, un planification plus intelligente, l’optimisation des ressources, la recompilation de graphes partiels et une coordination plus poussée entre les agents restent des domaines non explorés. En résumé : utilisez des instructions pour résoudre des tâches, et utilisez l’ingénierie de graphes pour construire des systèmes.

Pensées finales

Au début, on s’attendait à apprendre sur les graphes. Ce que cet exercice a vraiment enseigné, c’étaient les limites, la vérification et la coordination. Le graphe n’était pas ce qui comptait. Ce qui comptait, c’était un objectif clair pour chaque étape, une limite à ce qu’un agent peut croire, une définition de ce qu’il doit produire, ainsi qu’une preuve d’achèvement avant de passer à l’étape suivante.

Ce n’est pas la seule façon de construire des systèmes d’IA, et tous les flux de travail ne méritent pas une telle structure. Mais pour des tâches complexes, longues ou impliquant plusieurs agents, l’ingénierie des graphes offre une approche pratique pour créer des systèmes plus prévisibles et plus faciles à faire évoluer.

Si une seule phrase doit être mémorisée, qu’elle soit celle-ci : une instruction exprime le souhait, le contexte définit ce que l’agent peut considérer comme un fait, le contrat précise le résultat attendu, et le graphe est le mécanisme qui montre que le travail est terminé.

À l’époque de cette expérience, ContractGraph était encore en phase de développement, et son dépôt n’avait pas encore été publié, car son architecture devait d’abord être simplifiée. Pour une introduction plus complète sur ce sujet, cherchez un guide général sur l’ingénierie des graphes, car ce compte rendu ne couvre qu’un seul cadre de travail et non l’ensemble du domaine.