Anatomie d’un agent · Craftomancer

EN CHANTIER Cette section est en cours d’écriture : ce texte est lisible mais pas encore finalisé, son contenu peut évoluer.

« Ce qu’est un LLM » a posé la mécanique du modèle : une machine à continuer du texte, sans mémoire, dont le contexte est la seule réalité. Un agent, c’est cette même mécanique mise en boucle et équipée d’outils.

La première fois que j’ai vu un agent lancer ma suite de tests, lire l’échec et corriger son propre code sans que je touche à rien, j’ai eu la sensation très nette qu’un truc venait de changer de nature. Puis j’ai voulu comprendre ce qui tournait vraiment, et j’ai découvert que la magie tenait en trois pièces.

C’est quoi un agent, concrètement ?

Un agent, c’est trois pièces : un modèle, qui ne fait jamais qu’une chose, continuer du texte ; un harnais (l’application : CLI, extension d’IDE), qui exécute réellement les actions et reconstruit le contexte à chaque appel ; des outils, le répertoire d’actions que le harnais accepte d’exécuter pour le compte du modèle.

Pour situer, regardez le chemin parcouru. L’autocomplete propose une continuation, vous acceptez ou vous rejetez. Le chat ajoute le tour de parole : le modèle répond, vous copiez-collez, vous exécutez à sa place. L’agent franchit le pas qui restait — il agit sur l’environnement, et il lit le résultat de ses actions.

J’aime bien l’image de quelqu’un au téléphone qui vous dicte des commandes. Il connaît le shell par cœur, mais il n’a pas de clavier. C’est vous qui tapez, et vous qui lui lisez la sortie. Le modèle, c’est la voix au téléphone. Le harnais, c’est le clavier.

Gardez cette décomposition en tête, elle vous évitera une erreur d’attribution permanente. Je l’ai faite pendant des mois : je mettais sur le dos du modèle des comportements qui venaient entièrement du harnais. Ce que deux agents voient de votre repo, ce qu’ils ont le droit de faire, ce qu’ils retiennent entre les sessions — tout ça, c’est le harnais. Le modèle dessous est souvent rigoureusement le même.

Comment tourne la boucle agentique ?

En trois temps, répétés jusqu’à ce que le modèle rende une réponse sans demander d’outil :

le harnais assemble le contexte (instructions, historique, résultats d’outils précédents) et l’envoie au modèle ;
le modèle continue ce texte, soit par une réponse, soit par une demande d’appel d’outil : du texte structuré qui dit « exécute ceci » ;
le harnais exécute l’outil, capture le résultat, et l’injecte dans le contexte de l’itération suivante.

Retenez la répartition des rôles, tout en découle : le modèle demande, le harnais fait, le résultat revient en texte.

Et c’est bien cette boucle qui change la nature du travail. « Ce que le modèle sait » a établi que la sortie d’un modèle n’a pas à être digne de confiance, mais réfutable à bas coût. La boucle rend cette vérification automatique. Un agent qui peut lancer vos tests, lire l’échec et corriger converge vers du code qui passe, sans que vous arbitriez chaque étape.

Ce qui veut dire une chose très concrète : la qualité de votre outillage de vérification devient la qualité de votre agent.

pnpm test --filter api   # 1 échec : attendu 429, reçu 500

Une commande rapide, avec un message d’échec précis, c’est une boucle qui converge. Une commande lente au message vague, c’est un agent qui tâtonne en dépensant votre fenêtre.

Parce que la boucle a un coût, aussi. Chaque résultat d’outil — chaque fichier lu, chaque sortie de commande — s’ajoute à la fenêtre de contexte. Une session agentique la remplit vite, et l’attention se dilue à mesure.

C’est quoi un outil, pour un agent ?

Un contrat, rien de plus : un nom, une description, un schéma de paramètres. Le harnais présente ce catalogue au modèle — dans le contexte, comme tout le reste — et le modèle « choisit » un outil comme il fait tout le reste : en continuant le texte le plus plausible vu la tâche.

Le répertoire type d’un agent : lire et modifier des fichiers, chercher dans le code, exécuter des commandes shell, consulter le web. Vous pouvez y brancher les vôtres (serveurs d’outils, scripts maison) : ça étend le répertoire, ça ne change pas la mécanique.

Deux conséquences très pratiques :

Un agent ne « connaît » pas votre repo, il l’explore. Chaque information qu’il a sur votre code a été acquise par un appel d’outil, visible dans la session. Quand il se trompe sur l’état du projet, votre question de débogage n’est jamais « pourquoi il croit ça ? » mais « qu’a-t-il réellement lu ? ».
La description d’un outil est un prompt. Le modèle décide d’utiliser un outil sur la foi de sa description. Un outil mal décrit est un outil ignoré, ou employé de travers.

Jusqu’où autoriser un agent ?

Jusqu’à la limite du réversible. Tout ce que le modèle demande, le harnais peut le refuser : c’est le rôle du système de permissions — approbation action par action, listes blanches de commandes, modes plus ou moins autonomes, sandbox. C’est votre contrôle du rayon de dégâts, et franchement, c’est le seul dont vous disposez.

Alors dimensionnez-le au lieu de le laisser au réglage par défaut. Tout approuver à la main rend la boucle inutilisable — j’ai tenu deux jours avant de craquer. Tout autoriser confie votre machine à un processus qui optimise la plausibilité, pas la prudence.

Le bon critère, c’est la réversibilité, jamais la confiance accumulée :

Lire est gratuit. Laissez faire.
Écrire se défait avec git. Laissez faire, si le repo est propre.
Exécuter dépend de la commande. C’est là que ça se joue.

Et l’irréversible — pousser, déployer, migrer, supprimer hors du repo — mérite le point d’arrêt, toujours.

LE CRAFTOMANCER

L’autonomie d’un agent ne se mérite pas, elle se borne. Un agent qui a eu raison cent fois produira la cent-unième commande de la même façon, justifiée ou non. N’élargissez jamais les permissions parce que « ça se passe bien » : élargissez-les parce que le filet mécanique en dessous (git, sandbox, environnement jetable) rend l’erreur réparable.

Pourquoi les agents vivent dans le terminal ?

Parce que c’est l’interface universelle des outils de développement, et que tout y entre et tout en sort en texte — le médium natif du modèle. Un seul outil shell donne accès à git, aux tests, aux linters, aux générateurs, à tout ce que votre projet expose en ligne de commande, sans la moindre intégration spécifique.

D’où cette règle que je répète à qui veut l’entendre : la surface CLI de votre projet définit ce que l’agent sait faire. J’ai passé une matinée à regarder un agent tourner en rond sur un projet dont le build ne se lançait que depuis l’IDE. Il ne pouvait pas vérifier son travail, donc il ne convergeait vers rien.

Rendre un projet « agent-ready », c’est d’abord le rendre pilotable et vérifiable depuis un shell. Rien de neuf : c’est ce qu’exigeait déjà une CI correcte.

En pratique

Distinguez modèle et harnais : la plupart des comportements à déboguer (contexte, permissions, mémoire de session) appartiennent au harnais.
La boucle ne converge que vers ce que vos outils vérifient : investissez dans des commandes de test et de build rapides, aux échecs explicites.
Chaque appel d’outil remplit la fenêtre. Les longues sessions diluent l’attention : redémarrez plutôt que d’insister.
Calibrez les permissions sur la réversibilité des actions, et n’élargissez l’autonomie qu’adossée à un filet mécanique (git, sandbox).
Auditez la surface CLI de votre projet : ce qui ne se pilote pas depuis un shell est invisible pour l’agent.

Vérifiez votre modèle

Quatre questions pour voir si la machine est bien démontée. Cliquez une réponse : le verdict s’affiche.

RUN · I 0 / 4

jack in — choisissez votre réponse

Quand un agent lance vos tests, qui exécute la commande ?

Deux agents ne voient pas les mêmes fichiers de votre repo. Ça vient d’où ?

Sur quoi calibrer l’autonomie que vous accordez à un agent ?

Qu’est-ce qui rend concrètement un projet « agent-ready » ?

La machine est démontée ; reste à la nourrir. Prochaine étape : le dossier de contexte du projet, ce que l’agent doit lire avant la première ligne.