
La première fois que j'ai fait tourner de bout en bout la chaîne principale de l'Agent, je pensais que le plus dur était passé.
Le modèle peut être appelé, les données peuvent être persistées, les vecteurs peuvent être récupérés, et le workflow peut aller jusqu'au bout sans encombre. Pour quelqu'un qui réalisait un projet complet avec LangGraph pour la première fois, c'était déjà de quoi m'exciter un moment.
Mais c'est au moment où j'ai vraiment commencé à l'utiliser en continu que les problèmes ont surgi un par un : alors que le checkpoint était bien configuré, le modèle ne savait pas, au tour suivant, ce qui s'était passé au tour précédent ; le workflow était découpé très finement, mais l'état était bourré de produits intermédiaires qu'il était inutile de sauvegarder ; la base de données contenait pas mal d'informations, mais le contexte reçu par le modèle n'était pas forcément utile.
Le plus pénible, c'était que chaque fois qu'un besoin produit changeait, je devais d'abord expliquer pourquoi l'architecture existante ne soutenait pas vraiment ce besoin, puis chercher un moyen de l'y faire entrer de force.
Finalement, j'ai décidé de réécrire.
Pour faciliter la discussion, je masque ci-dessous le métier concret du projet et je le considère comme un Agent conversationnel qui doit accumuler du contexte en continu et prendre en charge des interactions multi-tours. Cet article ne compte pas non plus énumérer la stack technique ; je préfère parler des endroits qui m'ont réellement bloqué, et de la façon dont ces problèmes ont changé ma compréhension du développement d'Agent.
I. J'ai pris l'état du workflow pour la mémoire du modèle
L'architecture initiale était un Pipeline assez long : charger l'objet métier, organiser les données de base, construire la requête de récupération, récupérer les informations, organiser le contexte, puis enfin appeler le modèle.
Pour faciliter le passage de données entre les nœuds, j'ai mis à peu près tout ce qui était produit en cours de route dans le Graph State. Les résultats de requête, les requêtes de récupération, le contexte à moitié organisé, et même les instances ORM de SQLAlchemy, j'y fourrais tout.
À l'époque, ma compréhension était simple : le State, ce n'est pas juste les données partagées entre les nœuds ? On les met dedans, le nœud suivant les récupère directement, c'est tellement pratique.
Jusqu'à ce que je branche le checkpoint, et là, problème.
D'abord la sérialisation. Les instances ORM ne peuvent pas être confiées comme un simple dictionnaire à la chaîne de sérialisation du checkpoint de l'époque. Ensuite, la portée de la persistance : beaucoup de données temporaires utiles seulement à l'exécution en cours ont été sauvegardées avec l'état.
Ma première correction a été de vider les champs intermédiaires dans le dernier nœud. Ce n'est qu'ensuite que j'ai compris que le checkpoint enregistre l'état pendant l'exécution, et qu'un vidage final n'efface pas les instantanés déjà écrits auparavant.
Mais ce n'était pas encore le plus gros piège.
Pour prendre en charge les questions de suivi, je voulais que le deuxième tour réutilise directement le contexte sauvegardé au premier tour, en évitant une construction coûteuse. Je configurais le même thread_id, puis j'appelais le Graph, et le modèle se comportait toujours comme s'il n'avait jamais vu le tour précédent.
En regardant attentivement la chaîne, la raison était en fait très simple : l'état était restauré, mais au moment d'appeler le modèle, je ne construisais qu'un nouveau HumanMessage. L'historique restait dans le State, sans être organisé dans la requête courante, donc le modèle ne le voyait naturellement pas.
Plus absurde encore, dans l'entrée du deuxième tour, je passais aussi une chaîne vide au champ de contexte. Je voulais exprimer « on ne recalcule pas ce tour », mais l'effet réel était d'écraser l'état existant avec une valeur vide…
C'est après cette expérience que j'ai vraiment séparé plusieurs choses :
| Données | Rôle dans le système |
|---|---|
| Variables temporaires internes au nœud | Servent à l'étape courante, jetables une fois terminées |
| Graph State | État d'exécution transmis entre les nœuds et restauré selon les besoins |
| Historique des messages | Contenu de dialogue à conserver lors des interactions multi-tours |
| Entrée du modèle pour ce tour | Informations dont la tâche courante a réellement besoin |
Le checkpoint peut aider à restaurer l'état d'exécution, mais quels contenus entrent dans l'entrée du modèle, cela reste à concevoir par moi-même. À l'inverse, un State volumineux ne signifie pas forcément que chaque requête consommera beaucoup de tokens ; ce n'est qu'en envoyant ces contenus au modèle qu'ils deviennent un coût d'entrée.
Cette distinction paraît très basique, mais il m'a vraiment fallu me planter une fois pour la comprendre.
J'ai aussi repensé le découpage des nœuds. Avant, je découpais presque un nœud par fonction, puis je suis allé à l'autre extrême en remettant toute la chaîne dans un seul nœud. En continuant, j'ai compris que la frontière des nœuds doit suivre les besoins d'exécution : les étapes qui nécessitent une observation indépendante, un routage conditionnel ou une planification parallèle gagnent à être séparées ; une logique de transformation purement locale se contente d'une fonction ordinaire.

II. Si le modèle est lent, c'est parfois que je lui ai posé un problème trop difficile
Il y avait au début une chaîne d'entrée qui devait restaurer des enregistrements structurés à partir de captures d'écran.
Je demandais au modèle d'identifier pour chaque message l'émetteur, le contenu et l'heure, puis de les organiser en JSON strict. Pour améliorer la précision, j'imposais aussi pas mal de contraintes à l'utilisateur : captures envoyées dans l'ordre, avec l'heure, nombre d'images limité, etc.
Le résultat n'était pas satisfaisant. Lors d'un essai, deux captures ont pris environ deux minutes, et il restait des confusions d'heure, des émetteurs décalés et des contenus invalides.
La première réaction a bien sûr été de continuer à ajuster le prompt. Mais en regardant à nouveau l'usage final, j'ai soudain réalisé que je n'avais pas besoin de restaurer chaque enregistrement original sans en omettre un.
Ce dont l'aval avait réellement besoin, c'était : autour de quel thème s'organise ce matériel, quelles informations valent la peine d'être conservées, et dans quel contexte elles se produisent.
J'ai donc ajusté la granularité des données, passant de « chaque enregistrement original » à « des informations organisées autour d'un thème ». Le modèle n'assume plus la restauration complète des enregistrements, et la récupération ultérieure n'a plus besoin de reconstruire la sémantique à partir d'une masse de messages épars.
Bien sûr, cette solution avait aussi un coût à l'époque : j'exigeais que les matériaux soumis en une fois par l'utilisateur appartiennent autant que possible au même thème, ce qui revenait à rendre une partie du travail de segmentation à l'utilisateur. Cela allégeait la charge de traitement, mais ne réglait pas complètement l'expérience d'entrée.
Cette affaire m'a amené à prendre l'habitude, avant d'optimiser le modèle, de me poser deux questions : de quelles informations la fonctionnalité finale a-t-elle réellement besoin ? La granularité que je demande actuellement au modèle dépasse-t-elle l'usage réel ?
Ce n'est pas parce que la base de données peut contenir les enregistrements originaux que le modèle doit les reconstruire un par un ; ce n'est pas parce que le modèle peut produire une structure complexe que le produit a besoin que l'utilisateur attende qu'il la remplisse.
III. La difficulté du contexte passe de « le stocker » à « comment l'utiliser ce tour-ci »
Au début, quand je faisais de la mémoire, mon attention portait surtout sur l'écriture : comment extraire les données, comment modéliser les données, comment vectoriser le texte.
Ensuite, en découvrant des solutions qui organisent le contexte en Markdown, j'ai trouvé qu'elles avaient beaucoup à apprendre en matière de classification et d'expression de l'information. Mais parmi les solutions que j'ai essayées, certains fichiers devaient être lus à chaque tour, tandis que d'autres étaient chargés intégralement à la demande.
Quand les données sont peu nombreuses, c'est très direct. À mesure qu'elles augmentent, j'ai commencé à craindre qu'à chaque fois qu'on n'a besoin que d'une petite partie de l'information, il faille d'abord charger tout le fichier.
Lors de la refonte, j'ai donc conservé les données de base et découpé les informations plus fines en entrées indépendantes, pour permettre une récupération ultérieure selon la question. Ici, la base de données gère l'appartenance, la classification et le temps des entrées, tandis que le contenu textuel exprime la sémantique que le modèle doit comprendre.
Mais avec la récupération vectorielle, le problème ne disparaît pas automatiquement.
Au début, la récupération reposait principalement sur la distance sémantique. Ensuite, j'ai progressivement ajouté le filtrage par périmètre métier, les pondérations d'importance et une décroissance temporelle pour certaines informations. Parce que « très similaire à la question » et « adapté pour répondre à la question actuelle », ce n'est pas la même chose.
Surtout le temps.
Je mettais autrefois seulement un « temps actuel » dans le prompt système, avant de comprendre que cela ne pouvait pas indiquer quand les messages historiques s'étaient produits. En remontant plus en amont, même si la base de données a une date de création, si le texte extrait perd l'année, la période ou la phase du matériel original, le modèle continue facilement de confondre des choses similaires survenues à des moments différents.
Les ajustements ultérieurs se sont divisés en deux parties : les messages de dialogue portent explicitement un horodatage ; lors de l'extraction, les ancrages temporels confirmables du matériel sont conservés dans le corps du texte, et les temps indéterminables ne sont pas complétés.
C'est plus en amont qu'un simple ajustement de formule de tri. Si l'information temporelle est perdue à l'extraction, il est difficile de la retrouver de toutes pièces au stade de la récupération.
Par ailleurs, j'ai aussi essayé d'encapsuler la récupération de connaissances en Tool, pour que le modèle décide quand il a besoin de compléter des données, afin d'éviter d'exécuter mécaniquement toute la récupération à chaque tour.
Mais le Tool Call a révélé une autre frontière : le modèle ne peut pas générer de manière stable l'ID de l'objet métier courant. Cet ID est pourtant déjà dans le contexte d'exécution du système, et je demandais encore au modèle de le deviner.
Finalement, j'injecte avant l'exécution de l'outil les paramètres déjà déterminés dans le contexte courant. Le modèle peut décider s'il faut récupérer et quoi récupérer ; quant à savoir qui est l'utilisateur actuel, sur quel objet il opère et s'il a le droit d'y accéder, c'est au programme de le déterminer et de le vérifier.
Après avoir traité ces problèmes, ma compréhension du contexte est passée de « collecter autant que possible » à : conserver les informations nécessaires pour la tâche courante et les faire entrer dans le modèle sous une forme appropriée.
Quant à savoir combien chaque modification a réellement amélioré les résultats, je n'ai pas assez de données d'évaluation systématiques, et je ne veux pas inventer un pourcentage ici. Ce que je peux confirmer, c'est que je commence à savoir sur quelle chaîne enquêter, au lieu de me focaliser uniquement sur la réponse finale en ajustant les prompts.
IV. Avoir découpé les répertoires ne signifie pas être vraiment découplé
Dans mes anciens projets Web, j'avais l'habitude d'écrire d'abord le backend, puis d'envelopper une interface HTTP, et enfin de la donner à appeler au frontend. Cet Agent a d'abord suivi une structure similaire, avec les capacités métier et le service Web très proches.
Ensuite, le produit interagissant principalement via IM, j'ai ajouté une CLI pour exécuter des opérations de configuration, d'administration et de diagnostic. À ce stade, il devenait très gênant que la couche métier continue de dépendre du framework Web.
J'ai donc extrait le Service, pour qu'il porte les capacités métier et d'accès aux données, puis que différentes entrées l'appellent.
Ça a l'air découplé, non ? La réalité m'a encore frappé.
Une fois, en exécutant la commande d'aide de la CLI, la sortie était en fait l'aide du framework Web.
La raison : le module de commande importait le Service, et le Service importait au niveau supérieur le type Request du framework Web. Ce n'était à l'origine qu'une annotation de type, mais à l'exécution elle entraînait tout le framework et affectait l'analyse des arguments de ligne de commande.
La correction n'était pas compliquée : déplacer les dépendances de type pur sous TYPE_CHECKING, garder l'enregistrement des commandes aussi léger que possible, et ne charger les modules nécessaires qu'au moment de l'exécution réelle.
Mais cette petite affaire m'a fait comprendre que les flèches de dépendance sur le schéma d'architecture doivent finalement se concrétiser dans les imports de modules et le comportement d'initialisation. Un Service qui paraît très propre, si l'importer entraîne le framework, lit des arguments ou démarre des connexions externes, les problèmes resurgiront dès qu'on l'appelle depuis une autre entrée.
Ensuite, pour simplifier la configuration utilisateur, j'ai aussi essayé de placer une partie des capacités de données à distance. Les endroits qui prenaient des objets ORM devaient être modifiés pour consommer des structures de retour explicites ; les opérations de base de données éparpillées dans les entrées et le Graph devaient aussi continuer à être ramenées vers le Service.
J'ai ajouté une couche de distribution unifiée : le mode local appelle le Service, le mode distant appelle l'API HTTP correspondante. La sérialisation est aussi traitée à cette frontière, pour éviter que les conversions d'énumérations, d'objets temporels et de paramètres optionnels ne se dispersent partout.
Par exemple, un paramètre de requête par défaut : passer None dans une fonction Python est naturel, mais à l'encodage d'une query HTTP, cela peut directement provoquer une erreur. La correction doit être contenue à la frontière de la requête, tout en conservant les valeurs réellement significatives comme 0 et False ; il ne faut pas non plus supprimer au passage le null explicite du corps de requête JSON.
Ce ne sont pas des algorithmes complexes, mais ils déterminent si « une fonction appelable localement » peut devenir une interface distante fiable.
V. Un utilisateur configure une base de données en moins, le système assume une série de responsabilités en plus
La CLI et l'entrée IM visaient au départ à réduire le développement d'un frontend indépendant et à permettre aux utilisateurs d'interagir dans un environnement familier.
Mais en enchaînant le processus d'installation, j'ai réalisé que je n'avais fait qu'économiser le frontend : l'utilisateur devait toujours préparer la base de données, la configuration du modèle et la configuration du bot. Le code peut tourner, mais il y a encore un long chemin entre cela et l'envie de l'utiliser.
J'ai donc essayé de faire porter l'accès à la base de données par le serveur, pour réduire la charge de création de base par l'utilisateur.
La première contrainte était claire : on ne peut pas, pour des raisons de commodité, envoyer au client les identifiants de connexion à la base de données partagée. Les opérations de données ordinaires peuvent passer par une API authentifiée, mais le checkpoint du workflow dépend d'une connexion à la base de données ; il n'obtiendra pas automatiquement une capacité de stockage distant parce que j'ai ajouté une route HTTP.
À l'époque, la solution était de conserver deux comportements : le mode local continuait d'utiliser PostgreSQL pour persister les checkpoints ; le mode partagé expérimental utilisait la mémoire du processus.
Le coût était clair aussi : après redémarrage du processus, cette partie de la mémoire à court terme du mode partagé serait perdue.
Je n'ai pas résolu complètement ce problème, j'ai seulement accepté une dégradation en échange d'un mode d'exécution qui n'expose pas la connexion à la base de données au client. Cela ne signifie pas non plus que le checkpoint ne pourra jamais être distant, mais cette couche de distribution ne pouvait pas le couvrir à l'époque, et le coût d'une abstraction supplémentaire dépassait déjà l'objectif de ce tour.
Le problème plus gênant était encore à venir.
Certains Services qui semblent être de la « synchronisation de données » appellent en réalité le modèle en interne. En les déplaçant côté serveur, quelle configuration de modèle faut-il utiliser ? Comment transmettre la configuration de l'utilisateur ? Qui supporte le coût des appels ?
Auparavant, sur une machine unique, la base de données, la configuration du modèle et l'environnement d'exécution étaient au même endroit, et ces questions étaient faciles à ignorer. Une fois le réseau franchi, chacune doit être à nouveau tranchée.
Il en va de même pour l'état de connexion. Pour réduire les interruptions de tâches en arrière-plan dues à l'expiration du token, j'ai un temps adopté un mode sans expiration. Mais les problèmes de rotation, de révocation et de gouvernance de l'invalidité restent présents ; on ne peut pas dire que l'authentification est complètement conçue simplement parce que la chaîne principale continue de fonctionner.
Finalement, bien qu'une partie de la chaîne du mode partagé ait déjà été connectée, j'ai quand même masqué l'entrée de configuration publique. Tant que l'appartenance de la configuration du modèle et la frontière de l'exécution déléguée côté serveur ne sont pas propres, il ne faut pas laisser l'utilisateur la considérer comme une option déjà prête.
C'est aussi un changement dans ma vision produit : réduire le coût d'utilisation signifie que quelqu'un doit assumer la complexité auparavant confiée à l'utilisateur. Si l'utilisateur n'a plus à configurer la base de données, le serveur doit reprendre les responsabilités correspondantes en matière de permissions, de configuration et d'exécution. Un « Easy Mode », c'est bien plus que masquer quelques champs de saisie.

VI. Une panne de service de prompts m'a fait reconsidérer les dépendances d'exécution
Il y a eu une autre leçon, qui n'avait presque rien à voir avec les capacités du modèle.
Pour faciliter l'optimisation, je plaçais les prompts sur une plateforme externe, récupérés en temps réel à l'exécution. Modifier un prompt ne nécessitait pas de redéployer, l'expérience de développement était vraiment bonne.
Puis le service de la plateforme est tombé en panne.
Je n'avais ni sauvegarde locale, ni mécanisme de secours en cas d'échec de lecture, et toutes les chaînes impliquant des prompts se sont effondrées d'un coup. Le service externe s'est rétabli environ deux jours plus tard, mais ces deux jours ont suffi à me faire comprendre : j'avais transformé un outil de confort de développement en dépendance dure à l'exécution.
La leçon de cette affaire est très concrète. Bien qu'un prompt soit un texte, il porte dans le système une logique d'exécution réelle ; sa version, sa sauvegarde et sa disponibilité doivent être prises au sérieux. Le placer en gestion distante ne fait pas disparaître ces responsabilités.
Au cours du développement ultérieur, j'ai aussi commencé à consigner les exigences de collaboration récurrentes sous forme de Skills : effectuer un contrôle qualité après modification, consigner les changements, synchroniser la documentation Graph, et réintégrer les corrections dans les règles.
Ces procédures ne remplacent pas les tests et ne garantissent pas que l'Agent s'exécute correctement à chaque fois. Mais au moins, lorsqu'une même omission se reproduit, j'ai la possibilité de modifier une règle continuellement consommée, plutôt que de simplement rappeler une fois de plus.
Pour finir
Avec le recul, cette réécriture n'est pas le fruit d'un jour où j'aurais compris tous les problèmes d'un coup, tracé une nouvelle architecture, puis tout réalisé en une seule fois.
J'ai d'abord mal compris le checkpoint, puis j'ai repensé l'état ; j'ai d'abord recherché une entrée à granularité fine, puis je suis revenu à la sémantique réellement nécessaire en aval ; j'ai d'abord découpé la couche métier et supprimé les points d'entrée inutiles, puis, pour le nouveau mode de déploiement, j'ai réintégré le service HTTP. De nouveaux problèmes surgissent sans cesse, et les choix déjà faits sont eux aussi réexaminés.
Je ne me torture plus particulièrement l'esprit avec la question « le choix de framework initial était-il erroné ». Ce qui m'a réellement fait prendre des détours, c'est de ne pas avoir clarifié des frontières plus fondamentales : ce qui doit être persisté, ce qui doit entrer dans le modèle, quels paramètres sont décidés par le programme, et quelles responsabilités une capacité emporte avec elle lorsqu'elle change de lieu d'exécution.
Aujourd'hui, quand je commence à écrire une nouvelle fonctionnalité, je prends un peu plus de temps qu'avant pour me poser ces questions. Elles ne me permettront pas forcément de réussir du premier coup, mais elles m'éviteront d'écrire du code qui semble déjà terminé et qu'il faut pourtant jeter dès que le contexte change.
Quant à cette réécriture, le résultat que je souhaite le plus conserver, ce sont probablement ces questions qui continueront ensuite d'influencer ma façon d'écrire du code.