J'ai analysé 300 logs d'échecs d'agents. Le problème n'était jamais le prompt.

Trois cents logs d’échecs d’agents. Je les ai épluchés sur deux semaines, en classifiant chacun par cause racine. Le résultat m’a surpris : les problèmes de prompt représentaient à peine 12 %. Le reste ? Le contexte était soit contaminé, soit débordant, soit complètement absent. Changer de modèle n’aidait pas. Changer d’outils non plus. Le schéma se répétait à chaque fois.

Je travaille sur le context engineering depuis un moment, alors quand un projet open-source appelé Agent Skills for Context Engineering a fait son apparition et dépassé rapidement les 10 000 étoiles GitHub, j’y ai prêté attention. Il est sous licence MIT, développé par un context engineer nommé Muratcan Koylan, et cité dans un article d’un laboratoire d’IA de l’Université de Pékin. C’est cette dernière information qui m’a poussé à le cloner.

Des fenêtres de contexte plus petites sont plus précises

J’assumais que bourrer le contexte de tokens serait toujours bénéfique. J’avais tort. Le premier principe de cet ensemble de compétences est : “densité d’information, pas volume d’information.”

Plus le contexte s’allonge, plus les modèles perdent le fil de ce qui se trouve au milieu. C’est l’effet en U : le modèle lit bien le début et la fin, mais survole tout ce qui se trouve entre les deux. Je l’ai testé moi-même en remplissant le contexte jusqu’à 128K tokens, puis en compressant les mêmes informations à 32K. La version compressée a obtenu de meilleurs scores de précision.

Le coût de traitement ne croît pas linéairement avec le nombre de tokens, il augmente de façon exponentielle. Réduire le contexte de moitié a diminué la latence de réponse de 40 à 60 %. Même avec le prefix caching, les longues entrées restent coûteuses. En une phrase : ce qui compte, c’est la quantité d’information utile que vous faites tenir dans un budget de tokens donné.

Les descriptions d’outils déterminent 80 % des performances d’un agent

Vous pouvez rédiger un prompt parfait, mais si vos descriptions d’outils sont bâclées, l’agent choisit le mauvais outil. Cet ensemble de compétences le formule très bien : “Les outils sont des contrats lus par des LLMs, pas par des humains.” Quand mon équipe a construit un serveur MCP, nous avons réécrit nos descriptions d’outils en suivant ce guide. Les échecs de sélection d’outils ont notablement diminué.

Chaque description d’outil doit préciser quand l’utiliser et ce qu’il retourne. Quand deux outils se chevauchent dans leur fonction, les humains sont confus, et les agents le sont encore plus. Un outil complet et polyvalent bat généralement plusieurs outils étroits. Et les messages d’erreur doivent indiquer à l’agent ce qu’il doit faire ensuite, pas seulement ce qui s’est mal passé.

Les systèmes multi-agents ont besoin d’une architecture avant les agents

Lancer plusieurs agents et espérer qu’ils collaborent automatiquement relève du voeu pieux. Le dépôt définit trois patterns clairement : un orchestrateur dirigeant des agents subordonnés, un modèle peer-to-peer où les agents communiquent entre égaux, et une chaîne de délégation hiérarchique.

Après avoir testé les trois en production, le pattern orchestrateur s’est avéré le plus prévisible et le plus facile à déboguer. Les agents subordonnés transmettaient leurs résultats via le système de fichiers. Le modèle peer-to-peer fonctionnait mieux pour les tâches créatives, mais risquait des boucles infinies. Pour les requêtes structurées, les fichiers partagés surpassaient la recherche vectorielle. En pratique, j’ai trouvé que trois agents représentaient le plafond de stabilité.

La recherche vectorielle seule ne suffit pas pour la mémoire

La recherche vectorielle retrouve facilement “Le client X a acheté le produit Y à la date Z”. Elle ne peut pas répondre à “Qu’est-ce que les clients qui ont acheté le produit Y ont également acheté ?” L’information relationnelle se perd dans les embeddings.

Cet ensemble de compétences propose une architecture mémoire à quatre niveaux : la mémoire de travail dans la fenêtre de contexte, la mémoire à court terme au sein d’une session, la mémoire à long terme entre les sessions, et la mémoire permanente sous forme d’archives. Le pattern “système de fichiers comme mémoire” est celui que j’ai trouvé le plus pratique. On navigue dans le contexte avec ls et grep plutôt qu’avec des requêtes d’embedding. Déverser les résultats des outils dans un fichier scratchpad a permis d’économiser considérablement l’espace de la fenêtre de contexte.

L’évaluation est la compétence la plus sous-estimée des agents

C’est la section que j’ai failli passer, et elle s’est révélée la plus précieuse. Le dépôt inclut un framework d’évaluation en TypeScript qui utilise des LLMs comme juges. Il génère même automatiquement des rubriques de notation.

Ce qui m’a impressionné, c’est la mitigation du biais de position. Lorsqu’on compare deux réponses côte à côte, le framework évalue deux fois en inversant l’ordre. Cela contrebalance la tendance à noter plus favorablement la réponse qui apparaît en premier. Il supporte à la fois la notation directe et la comparaison par paires. Construire un pipeline d’évaluation m’a enfin permis de mesurer si les modifications de prompt amélioraient réellement les performances, au lieu de le deviner.

Un point que le dépôt ne résout pas : les rubriques d’évaluation nécessitent encore une calibration humaine. Les rubriques générées automatiquement donnaient de bons points de départ, mais j’ai dû ajuster les pondérations des scores pour mon domaine spécifique avant que les résultats deviennent fiables.

Quand votre agent se trompe, examinez le contexte avant d’accuser le modèle. Le dépôt est ici.