Les 4 outils qui font que ton agent marche, peu importe le modèle

juillet 2026 · 13 min de lecture

Les 4 outils qui font que ton agent marche, peu importe le modèle

Parce que le levier n'est pas le modèle. C'est ce que tu construis autour.

Pourquoi ce guide existe

Il sort un nouveau modèle toutes les deux semaines et la question revient à chaque fois : est-ce qu'il faut changer ?

La réponse est presque toujours non. LangChain l'a démontré publiquement : leur agent de code est passé de la 30ème place au top 5 sur Terminal Bench 2.0 sans changer de modèle. Uniquement en retravaillant ce qu'ils appellent le harness — l'architecture autour du modèle : boucles de vérification, injection de contexte, détection de boucles infinies, et une répartition de l'effort de raisonnement concentrée sur la planification et la vérification.

L'article : blog.langchain.com/improving-deep-agents-with-harness-engineering

Ce guide couvre quatre outils qui agissent chacun sur une couche différente de cette architecture. Ils sont indépendants les uns des autres : tu peux en installer un seul.

Vue d'ensemble

Outil	Le problème qu'il règle	Install
Context7	L'agent invente des fonctions qui n'existent plus	`npx ctx7 setup`
semble	L'agent lit quinze fichiers pour trouver une ligne	`uvx semble install`
headroom	Un log de 2000 lignes sature ton contexte	`pip install "headroom-ai[all]"`
statewright	40 outils dispo, l'agent part dans tous les sens	via plugin Claude Code

Si tu n'en installes qu'un : Context7. C'est le plus rapide à mettre en place et le problème qu'il règle est universel.

1. Context7 — la doc à jour

Le problème

Tu demandes un truc à ton agent. Il te sort une fonction qui n'existe pas, ou une syntaxe dépréciée depuis deux versions. Tu perds vingt minutes à comprendre pourquoi ça ne marche pas.

La cause est simple : le modèle a appris sur une version de la librairie qui date. Il ne le sait pas, et il ne peut pas le savoir.

Ce que fait Context7

Il va chercher la documentation à jour, spécifique à ta version, et l'injecte directement dans le prompt. Plus de changement d'onglet, plus d'API hallucinées, plus de code généré sur des versions périmées.

Deux outils sont exposés à l'agent : resolve-library-id (traduire un nom de librairie en identifiant Context7) et get-library-docs (récupérer la doc, avec un filtrage optionnel par sujet — "routing", "hooks", etc.).

Installation

La méthode recommandée aujourd'hui, une seule commande depuis ton projet (Node 18+) :

npx ctx7 setup

Ça authentifie via OAuth, génère une clé API et installe le bon skill. Tu choisis entre le mode CLI + Skills et le mode MCP. Les options --cursor, --claude ou --opencode ciblent un agent précis.

Pour désinstaller : npx ctx7 remove.

Configuration manuelle, si tu préfères passer par le MCP classique :

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "TA_CLE"]
    }
  }
}

Ou en HTTP, sans installation locale :

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "TA_CLE" }
    }
  }
}

En pratique

Le mode le plus simple : tu ajoutes use context7 à ta demande.

Crée un projet Next.js de base avec l'app router. use context7

Avec le skill installé, ça se déclenche souvent tout seul quand l'agent touche à une librairie externe.

Ce qu'il faut savoir

Une clé API gratuite s'obtient sur context7.com/dashboard et augmente les limites de débit. Sans clé, ça marche mais tu peux te faire limiter.

Et la doc vient des projets eux-mêmes : les projets listés dans Context7 sont maintenus par leurs propriétaires respectifs, pas par Context7. Donc si une librairie a une doc pauvre, Context7 ne la rendra pas meilleure.

Repo : github.com/upstash/context7

2. semble — la recherche de code

Le problème

Tu demandes à ton agent de modifier une ligne. Il ne sait pas où elle est. Alors il fait un grep, puis il ouvre un fichier, puis un autre, puis quinze. Chaque fichier lu entre dans le contexte, et tu le paies.

C'est le coût invisible le plus important dans une session de code : l'agent passe le plus clair de son budget de tokens à chercher, pas à travailler.

Ce que fait semble

C'est une bibliothèque de recherche de code conçue pour les agents. Elle renvoie exactement les extraits dont ils ont besoin, en utilisant environ 98% de tokens en moins qu'un grep suivi d'une lecture. L'indexation et la recherche d'une codebase complète prennent moins d'une seconde — environ 200 fois plus vite à l'indexation et 10 fois plus vite en requête qu'un transformer spécialisé code, tout en conservant 99% de sa qualité de récupération. Tout tourne sur CPU, sans clé API, sans GPU et sans service externe.

Ton agent interroge semble en langage naturel — par exemple "comment l'authentification est-elle gérée ?" — et récupère uniquement les extraits de code pertinents, sans avoir à grepper ni à lire des fichiers entiers.

Les chiffres précis : indexation d'un repo en environ 250 ms, requêtes résolues en 1,5 ms, NDCG@10 de 0,854 — soit 99% de la qualité du modèle CodeRankEmbed Hybrid, bien plus lourd.

Techniquement, ça combine des embeddings statiques Model2Vec avec une recherche lexicale BM25 et une fusion Reciprocal Rank.

Installation

L'installateur interactif est le plus simple :

uvx semble install

Ou via pip :

pip install semble
semble install

semble install détecte tes agents installés (Claude Code, Cursor, Codex, Gemini, OpenCode et d'autres) et te laisse choisir les intégrations à activer : serveur MCP, instructions CLI dans AGENTS.md, ou sous-agent dédié. Pour annuler, semble uninstall.

Configuration MCP manuelle :

{
  "mcpServers": {
    "semble": { "command": "uvx", "args": ["semble"] }
  }
}

En pratique

Une fois installé, tu ne fais rien de spécial : ton agent l'utilise à la place de grep. Tu le vois au nombre de fichiers qu'il n'ouvre plus.

En mode MCP, un watcher détecte les changements et déclenche une reconstruction automatique de l'index, qui reste donc à jour dans la session. semble lit les fichiers .gitignore et .sembleignore pour déterminer ce qu'il indexe.

Une chose à savoir : si un fichier est ajouté, supprimé ou modifié, ou si les paramètres d'indexation changent, l'index est entièrement reconstruit. Sur un très gros repo, ça peut se sentir.

Il y a aussi une API Python si tu veux t'en servir en dehors d'un agent :

from semble import SembleIndex
index = SembleIndex.from_path("./mon-projet")
results = index.search("sauvegarder le modèle sur disque", top_k=3)

Repo : github.com/MinishLab/semble — licence MIT

3. headroom — la compression de ce qui rentre

Le problème

Tu lances une commande, elle te crache 2000 lignes de log. Ça part intégralement dans le contexte. L'agent sature, commence à oublier le début de la conversation, et la qualité chute d'un coup.

Même chose avec un retour d'API qui renvoie un JSON de 500 objets dont tu as besoin de trois champs.

Ce que fait headroom

Il s'intercale entre ton agent et le modèle, et compresse tout ce qui rentre : sorties d'outils, logs, fichiers, chunks de RAG, historique de conversation.

L'exemple du README : une recherche dans des logs passe de 10 144 à 1 260 tokens, en trouvant le même FATAL.

Le point important : rien n'est jeté. Les originaux restent dans un Compressed Store, et si le modèle a besoin du détail complet, il appelle headroom_retrieve. La compression est réversible.

Le routage est automatique selon le type de contenu : le JSON part vers SmartCrusher, le code passe par une compression consciente de l'AST (Python, JS, Go, Rust, Java, C++), le texte va vers Kompress.

⚠️ Le chiffre à ne pas mal citer

Le repo affiche aujourd'hui : 20% de tokens en moins pour les agents de code, 60 à 95% pour du JSON.

Le "60-95%" circule partout comme s'il s'appliquait à tout. C'est faux. Ce chiffre concerne les données structurées. Sur une session de code classique, attends-toi à ~20%.

Ça reste intéressant — 20% sur une facture Opus, ce n'est pas rien — mais ne promets pas 90% à quelqu'un qui fait du refactoring.

Installation

# Python, tout inclus
pip install "headroom-ai[all]"

# Node / TypeScript
npm install headroom-ai

# Docker
docker pull ghcr.io/chopratejas/headroom:latest

Python 3.10+ requis. Des extras granulaires existent si tu ne veux pas tout : [proxy], [mcp], [ml], [code], [memory], [relevance], [langchain], [agno], [evals].

Trois modes d'usage : proxy transparent (zéro changement de code), fonction Python compress(), ou serveur MCP. Claude Code, Codex, Cursor, Aider et Copilot CLI sont supportés via headroom wrap.

La fonctionnalité méconnue

Celle-là mérite d'être connue pour elle-même :

headroom learn           # analyse tes sessions passées, montre les recommandations
headroom learn --apply   # écrit les enseignements dans CLAUDE.md et MEMORY.md

Ça lit ton historique de conversation, repère chaque appel d'outil qui a échoué, le corrèle avec ce qui a fini par marcher, et écrit les corrections dans les fichiers de ton projet.

Autrement dit : ton agent apprend de ses erreurs passées. C'est peut-être la meilleure raison d'installer headroom, indépendamment de la compression.

Le coût

La compression ajoute entre 15 et 200 ms de latence. Sur Sonnet ou Opus c'est largement rentable. Sur un modèle rapide et pas cher, le calcul est moins évident.

Repo : github.com/chopratejas/headroom

4. statewright — un outil à la fois

Le problème

Un agent qui a 40 outils disponibles en permanence part dans tous les sens. Il édite pendant qu'il devrait planifier, il lance des commandes pendant qu'il devrait lire.

L'auteur, Ben Cochran, résume bien l'intuition : au lieu de rendre le modèle plus gros, rendre le problème plus petit.

Ce que fait statewright

C'est un système de garde-fous en machine à états pour agents de code : il contraint les outils disponibles selon la phase du workflow. Lecture seule pendant la planification, outils d'édition pendant l'implémentation, commandes de test uniquement pendant les tests. Le moteur est en Rust, déterministe, sans LLM dans la boucle. L'intégration passe par MCP et des hooks, avec Claude Code, Codex, Cursor, opencode et Pi.

Le modèle voit 5 outils au lieu de dizaines, reçoit des instructions claires pour la phase en cours, et transitionne quand les conditions sont remplies. Le système lui signale aussi quand il tente quelque chose hors périmètre, incorrect, ou quand il tourne en rond.

Les workflows sont définis en JSON : états, transitions, gardes, listes d'outils autorisés.

Le résultat, et son contexte exact

Sur un sous-ensemble de 5 tâches SWE-bench, deux modèles locaux (13,8 Go et 19,9 Go) sont passés de 2/10 à 10/10 avec les contraintes activées.

C'est spectaculaire. Mais le repo lui-même précise les limites, et il faut les connaître avant de citer le chiffre :

Les résultats viennent d'un sous-ensemble de 5 tâches SWE-bench, pas du benchmark complet de 2294 instances.
Le harness d'expérimentation (sélection des tâches, scoring des patchs, runs de contrôle) n'est pas encore publié. L'auteur l'a reconnu publiquement.
Le test portait sur des modèles locaux de 13 à 20 milliards de paramètres. Le gain sur Opus ou Sonnet n'est pas mesuré, et il y a de bonnes raisons de penser qu'il est plus faible : ces modèles gèrent déjà mieux un grand nombre d'outils.

⚠️ Ce n'est pas complètement gratuit ni complètement open source

Point important, parce qu'on le présente souvent à tort comme les trois autres :

Il y a un tier gratuit, mais le cloud managé gère le stockage des workflows et la passerelle MCP.
La licence est Apache 2.0 pour une partie, et FSL-1.1-ALv2 pour d'autres portions, qui basculeront en Apache 2.0 le 3 mai 2029.
Le projet inclut un brevet, avec un engagement couvrant les implémentations indépendantes des techniques décrites. Plusieurs commentateurs sur Hacker News ont dit que ce brevet les refroidissait. À toi de voir.

L'auto-hébergement est possible, et le moteur, le crate agent et la TUI de démo sont dans le repo.

Les autres limites, annoncées par le projet

Les définitions de workflow s'écrivent à la main, même si un agent peut en générer via statewright_create_workflow.
Sur Cursor, l'application des règles est consultative et non stricte : MCP seul ne peut pas bloquer les appels d'outils dans l'architecture de Cursor.
Si un workflow est trop restrictif, l'agent se retrouve bloqué. statewright_deactivate est la porte de sortie.

Installation

Depuis Claude Code, via le marketplace de plugins. Le processus ouvre ton navigateur, tu crées un compte sur statewright.ai, tu génères une clé, tu la colles.

Ensuite tu actives un workflow en langage naturel :

lance le workflow bugfix — corrige les tests qui échouent dans...

Le guide d'installation détaillé, l'écriture de workflows et la référence du schéma sont sur docs.statewright.ai.

Mon avis

C'est le plus intéressant conceptuellement et le plus engageant des quatre. Le brevet et le cloud managé en font un choix qui se réfléchit, pas un npm install anodin.

Si l'idée te parle mais que le modèle économique te gêne, retiens au moins le principe : réduire le nombre d'outils disponibles à chaque étape améliore les résultats. Tu peux déjà l'appliquer à la main dans tes propres agents.

Repo : github.com/statewright/statewright

Par où commencer

Jour 1. Context7. Une commande, effet immédiat, aucun engagement.

Jour 2. semble. Regarde ta consommation de tokens avant et après sur une même tâche — c'est là que tu verras si ton agent passait vraiment son temps à chercher.

La semaine d'après. headroom, mais commence par headroom learn plutôt que par la compression. C'est la partie la plus utile et la moins connue.

Quand tu as un workflow répétitif. statewright. Ça ne sert à rien sur des tâches ponctuelles, ça devient intéressant quand tu refais la même séquence toutes les semaines.

Pour aller plus loin

Tous ces outils viennent du même endroit : github.com/ai-boost/awesome-harness-engineering, une liste qui compile ce qui se fait en ingénierie de harnais. C'est aussi là que tu trouveras la recherche académique sur le sujet si tu veux creuser.

Les liens des quatre outils :

Context7 — github.com/upstash/context7
semble — github.com/MinishLab/semble
headroom — github.com/chopratejas/headroom
statewright — github.com/statewright/statewright · docs.statewright.ai

Et si tu veux qu'on le fasse pour toi

C'est ce type d'architecture qu'on met en place chez nos clients : le but n'est pas d'avoir le dernier modèle, c'est que ça continue de marcher quand le prochain sort.

Si tu veux qu'on regarde ton cas : ceepia.com

Informations vérifiées en juillet 2026. Ces projets bougent vite — vérifie les repos avant d'installer.