Hermes Agent : débugger quand une session déraille

Une session Hermes peut se mettre à dérailler sans message d’erreur clair. La qualité chute, un tool part au mauvais moment, une skill force un cadre absurde, ou tout devient simplement plus confus que d’habitude.

Ce tuto sert à reprendre la main proprement. Pas à disséquer le core Hermes, et pas à bricoler dix corrections à l’aveugle, mais à retrouver une session saine en isolant la vraie cause.

Ce que tu auras à la fin
Une méthode simple pour reconnaître qu’une session a vraiment déraillé, revenir à une base lisible, isoler une cause, puis réintroduire proprement ce qui doit l’être.

Pour qui est ce tuto
Tu veux comprendre pourquoi une session part de travers, pas juste la faire repartir par hasard.

Comment reconnaître qu’une session a vraiment déraillé

La première chose à faire n’est pas de corriger quoi que ce soit. C’est de nommer le problème. Beaucoup de sessions “qui déraillent” sont juste des sessions où la demande était mal formulée, ou des sessions où tu as changé d’attente en cours de route sans t’en rendre compte. Avant de toucher à ton setup, prends trente secondes pour poser ce que tu observes.

Quelques signaux qui indiquent qu’il se passe vraiment quelque chose :

Le ton ou la qualité des réponses chute nettement par rapport à tes sessions récentes sur des tâches similaires.
Un tool s’active alors qu’il n’a rien à faire là, ou au contraire reste silencieux quand tu t’attendais à ce qu’il soit utilisé.
Une skill force un format qui ne correspond pas à ta demande du jour.
L’agent répond en boucle, se contredit, ou perd le fil d’une consigne qu’il tenait sans effort d’habitude.
Tu n’arrives plus à dire précisément ce qui est actif dans la session.

Ce dernier point est le plus important. Si tu ne sais plus ce qui est branché et pourquoi, le problème n’est déjà plus seulement dans l’agent : il est dans ta lecture de ta propre session. C’est exactement à ce moment-là qu’il faut ralentir, pas accélérer.

La pire erreur : tout changer d’un coup

Le réflexe qui tue, c’est d’ouvrir cinq fronts en même temps. Tu changes de modèle, tu réécris ta config, tu désactives une skill, tu coupes un serveur MCP, tu modifies un tool, et tu relances en espérant que “ça va se débloquer”. Parfois ça marche, et c’est pire que si ça n’avait pas marché : tu viens de “réparer” quelque chose sans savoir ce que c’était.

Le problème est simple. Si tu modifies cinq variables et qu’une seule était en cause, tu ne sauras jamais laquelle. Tu as donc toujours quatre modifications aveugles dans ton setup, qui vont se payer plus tard, souvent au pire moment, sous une forme qui ne ressemblera plus du tout au symptôme initial.

La règle tient en une phrase : une variable à la fois. Ce n’est pas une posture de perfectionniste, c’est la seule manière d’apprendre quelque chose de ce qui est en train de se passer. Un débogage dont on ne tire aucune leçon n’est pas un débogage, c’est de la chance.

Revenir à la base la plus simple possible

Avant d’essayer d’isoler quoi que ce soit, reviens au point de comparaison le plus lisible que tu aies : un prompt simple, sans couches, ou avec le minimum absolu que tu utilisais avant que les choses se compliquent. L’objectif n’est pas de résoudre le problème tout de suite. L’objectif est de retrouver un état que tu comprends.

Ça peut vouloir dire ouvrir une nouvelle session, ne rien brancher de spécial, et reposer une demande équivalente dans sa forme la plus nue. Si à ce niveau-là tout fonctionne normalement, tu sais déjà quelque chose d’utile : le modèle répond, la base est saine, le problème est dans ce que tu empiles au-dessus. Si même la base est bizarre, tu sais aussi quelque chose d’utile, mais d’un autre ordre : tu dois regarder plus bas avant d’aller voir tes couches.

Cette étape ennuyeuse est souvent celle que les gens sautent, parce qu’elle donne l’impression de “ne rien réparer”. C’est faux. Elle te donne le point de comparaison dont tu as besoin pour toutes les étapes suivantes. Sans lui, tu navigues à vue.

Quand le problème vient de la demande

C’est la cause la plus fréquente et la plus honteusement négligée. Avant d’accuser le modèle, les tools ou les skills, relis ta demande à voix haute. Est-ce qu’elle est claire ? Est-ce qu’elle donne un cadre ? Est-ce qu’elle contient des critères de sortie contradictoires, du type “fais court mais détaillé, précis mais sans jargon, neutre mais avec un angle” ? Est-ce que tu demandes une chose et en attends une autre sans l’avoir écrite ?

Un bon test consiste à soumettre la même demande à l’agent dans une nouvelle session, sans rien d’autre, et à regarder ce qu’il en fait. Si la réponse est déjà étrange, le problème n’est pas chez Hermes : il est dans la consigne. Dans la moitié des cas, reformuler la demande règle le “bug” sans qu’une seule ligne de config n’ait été touchée.

Ce n’est pas vexant, c’est juste la réalité du terrain. Un agent exécute des consignes. Une consigne floue donne une réponse floue, et ce n’est pas un bug.

Quand le problème vient du modèle

Si la demande est propre et que le comportement est quand même hors des rails, regarde le modèle. Est-ce que tu viens d’en changer ? De changer de quantification, de contexte, de provider ? As-tu modifié un paramètre d’inférence sans le noter ? Les symptômes typiques d’un problème côté modèle sont assez reconnaissables : latence inhabituelle, réponses tronquées, suivi d’instructions qui se dégrade, cohérence qui s’effondre sur des demandes que le modèle tenait auparavant sans effort.

Reste ici prudent et surtout général. Les versions bougent, les builds changent, et deux modèles au même nom peuvent se comporter différemment selon la façon dont ils sont chargés. Le bon réflexe n’est pas d’entrer dans un benchmark improvisé, c’est de rejouer une tâche simple dans les conditions que tu connaissais d’avant. Si la différence saute aux yeux, tu as ton coupable. Si non, tu peux écarter cette hypothèse et passer à la suivante.

Évite la tentation de changer de modèle “pour voir” sans rien noter. Tu introduirais une nouvelle variable dans une situation que tu cherches justement à stabiliser.

Quand le problème vient d’un tool

Un tool qui déraille est souvent un tool utilisé à mauvais escient, pas un tool cassé. L’agent l’appelle quand il ne faudrait pas, l’appelle avec des paramètres bancals, ou interprète son résultat comme une vérité alors que ce n’est qu’une donnée brute à croiser.

Le test est simple : désactive temporairement le tool suspect, relance la même demande, et compare. Si la réponse redevient saine, tu as isolé la cause, et tu peux ensuite décider si tu veux revoir le cadrage du tool, le garder désactivé pour ce type de tâche, ou juste mieux formuler ta demande quand il est actif.

Au passage, méfie-toi d’un piège classique : un tool qui renvoie une donnée factuelle donne un faux sentiment de réponse vérifiée. Ce n’est pas parce qu’un tool a parlé que ce qu’il a rapporté est pertinent pour la question. Un tool, c’est un capteur. Ce que l’agent en fait reste son problème, pas celui du capteur.

Quand le problème vient d’une skill

Les skills sont les dernières à être suspectées et souvent les premières responsables. Une skill, c’est une couche d’usage qui force un cadre. Quand la tâche du jour sort un peu de ce cadre, la skill continue pourtant de l’imposer, et le résultat se met à ressembler à quelque chose qui “marche presque” sans jamais vraiment coller à la demande.

Le test est le même que pour un tool : désactive la skill le temps de rejouer la tâche, et regarde ce qui change. Si la réponse redevient normale sans la skill, tu sais où regarder. Soit la skill est trop rigide et mérite d’être assouplie, soit elle n’est simplement pas adaptée à ce type de demande et tu devrais apprendre à la couper quand tu sors de son périmètre, soit elle n’avait finalement pas beaucoup de valeur et tu peux la retirer.

Une skill qui dégrade une session silencieusement est un cas classique, parce qu’elle ne produit aucune erreur bruyante. Elle se contente de biaiser le comportement.

Quand le problème vient de MCP

Si tu viens d’ajouter un serveur MCP, c’est le premier endroit où regarder. Pas parce que MCP est fragile par nature, mais parce qu’une couche ajoutée récemment est toujours une hypothèse prioritaire. Tout ce qui change le jour où ça se met à dérailler mérite d’être examiné avant ce qui tourne sans rien toucher depuis des semaines.

Les symptômes typiques d’un dérapage lié à MCP sont assez reconnaissables : capacités qui apparaissent ou disparaissent de façon confuse, comportements qui s’activent alors que tu ne les as pas demandés, ou à l’inverse la sensation que l’agent “ne sait plus quoi utiliser”. Dans tous les cas, le réflexe est le même : couper le serveur MCP ajouté, relancer la tâche, comparer. Si ça redevient lisible sans lui, tu as au moins isolé la zone.

Ça ne veut pas forcément dire que le serveur est mauvais. Ça veut dire qu’il introduit une couche que tu n’avais pas encore digérée dans ta routine, et qu’il faut décider en conscience si tu le gardes, à quelles conditions, et pour quels types de tâches.

La méthode simple pour débugger sans se perdre

Tout ce qui précède se résume à une discipline courte. Rien de magique, mais tenue sérieusement, elle règle l’essentiel.

Une variable à la fois. Tu changes une chose, tu testes, tu observes, tu notes. Pas deux.
Un test minimal. Une demande simple, représentative, que tu rejoues à l’identique à chaque étape pour comparer proprement.
Avant / après. Tu dois pouvoir dire ce que la modification a changé. Si tu ne peux pas, c’est que ton test n’était pas assez stable ou que tu as changé deux choses sans le voir.
Une trace écrite. Deux lignes dans un carnet, pas un rapport. Juste ce que tu as modifié, ce que tu as observé, et ce que tu as décidé d’en faire.
Réintroduction progressive. Une fois la cause identifiée, tu remets les couches une par une, en vérifiant à chaque étape que la session tient. C’est long la première fois, c’est rapide après.

Cette méthode n’a rien d’exotique. La seule difficulté, c’est de s’y tenir au lieu de tout retoucher d’un coup.

Les erreurs les plus fréquentes

Changer tout en même temps. Le réflexe panique. Tu en sors sans apprendre quoi que ce soit, et avec un setup que tu comprends moins qu’avant.
Ne pas avoir de point de comparaison. Si tu ne sais pas à quoi ressemblait l’état sain récent, tu ne sauras pas non plus à quoi reconnaître que tu y es revenu.
Croire qu’ajouter une couche va réparer le problème. C’est presque toujours l’inverse. Quand ça déraille, tu dois en retirer, pas en ajouter.
Ne plus savoir ce qui est actif. Un tool oublié, une skill restée branchée, un serveur MCP qui tourne en arrière-plan : tant que tu n’as pas cette vision, tout diagnostic est un tirage au sort.
Confondre un problème de qualité et un problème d’accès. Une réponse médiocre n’est pas la même chose qu’un tool qui ne répond plus ou qu’un serveur injoignable. Sépare les deux familles avant de chercher plus loin.
Vouloir conclure trop vite. Un test qui marche une fois ne prouve rien. Un test qui marche trois fois de suite sur la même base, c’est déjà plus sérieux.

Ce que tu ne dois pas faire

Ne panique pas et ne reconfigure pas tout dans la même soirée. Un setup reconstruit à chaud dans l’énervement est un setup que tu vas regretter la semaine suivante.
Ne modifie pas modèle, skill, tools et MCP dans la même session. Si tu dois absolument tout rejouer, fais-le par étapes, avec un test stable entre chaque.
Ne continue pas une session que tu ne comprends plus. Une session illisible ne se répare pas de l’intérieur. Ouvre-en une nouvelle, repars propre, et reviens à la précédente en sachant ce que tu cherches.
Ne garde pas des couches suspectes actives “pour voir”. Si tu soupçonnes une couche, tu la coupes, tu testes sans elle, et tu décides ensuite. Sinon tu pollues ton propre diagnostic.
N’oublie pas que la simplicité est souvent le meilleur outil de debug. La plupart des sessions qui déraillent redeviennent saines dès qu’on retire deux ou trois couches qu’on avait empilées sans vraiment en avoir besoin.

La suite logique

Tu as maintenant une méthode claire : nommer le symptôme, revenir à une base simple, isoler une variable, comparer, puis réintroduire. C’est sobre, et c’est justement le but.

Pour éviter d’avoir à faire ce boulot trop souvent, la suite logique est de garder un setup léger et maintenable. Et si tu sens que le problème vient surtout de l’usage quotidien, reviens à la routine propre pour l’utiliser au quotidien.