Il y a un mythe persistant selon lequel pour construire un assistant de code digne de ce nom, il faut absolument utiliser GPT ou Claude. C'est faux. Vous n'avez pas besoin d'un modèle à 1 trillion de paramètres. Vous avez besoin d'un modèle local de taille réduite et d'une ingénierie extrêmement rigoureuse autour de lui.
C'est d'ailleurs le sens de l'histoire pour les entreprises. Comme l'évoquait Mark Zuckerberg, l'avenir n'est pas à un modèle omniscient unique, mais à "chaque entreprise avec sa propre IA spécialisée". Et cette spécialisation passe obligatoirement par le fine-tuning et le déploiement local (ou sur serveurs souverains) pour garantir la sécurité des données.
La thèse derrière la construction de Vibrisse Agent tient en une phrase : Small models, Great tools.
Dans cet article, je vais détailler la stack technique et les solutions d'ingénierie concrètes que j'ai mises en place pour dompter un modèle local et le rendre fiable en production : LangGraph, Ollama, FastAPI, React (sans build step, avec CSS custom embarqué), le tout tournant sur une machine avec 32 Go de RAM.
Pour les curieux qui souhaitent lancer l'agent sur leur machine dès maintenant :
// MacOs / Linux
curl -sSL https://agent.vibrisse-studio.dev/install.sh | bash
// Windows
irm https://agent.vibrisse-studio.dev/install.ps1 | iex
L'Architecture : Pourquoi une Machine à États (LangGraph) ?
Au début, quand on construit une application LLM, on a tendance à penser en chaîne séquentielle : Input -> Prompt -> Outil -> Output. Le problème, c'est que si un nœud échoue, toute la chaîne s'arrête sans qu'on puisse rattraper l'erreur ou comprendre le contexte du plantage.
C'est là qu'intervient LangGraph. L'architecture de Vibrisse n'est pas une chaîne, c'est une machine à états. Chaque nœud du graphe a une responsabilité très précise, partage un état global de la conversation, et utilise des transitions conditionnelles pour passer au nœud suivant.
J'ai implémenté le pattern Supervisor / Worker :
- Le Supervisor analyse l'intention de l'utilisateur. Il ne fait rien d'autre que de router.
- Il dispatche la tâche vers des Workers spécialisés (le Worker RAG, le Worker Search, le Ghost Worker...).
- Si un Worker échoue ou a besoin de plus d'informations, il peut renvoyer l'état au Supervisor.
Le Vrai Combat : Dompter la "Paresse" des Petits Modèles
La partie la plus précieuse de ce projet — et celle que très peu de tutoriels documentent honnêtement — a été le combat contre la nature des petits LLM.
Le Choix des Armes : Les Modèles Vainqueurs
Si vous vous demandez quels modèles ont survécu à mes crash-tests : j'ai construit tout le cœur de l'agent autour de Gemma 4 (e4b). Pourquoi ? Parce qu'il intègre nativement la gestion de la vision et des "thoughts" (pensées), tout en offrant ce style de réponse très structuré à la Google. En revanche, pour tout ce qui est évaluation et métriques, j'ai dû basculer sur Llama 3 8B. Un trop petit modèle s'avère incapable d'évaluer ses propres réponses de façon fiable.
Contraintes et Pensée à Haute Voix
Sans contrainte stricte, un modèle local prendra toujours le chemin de la moindre résistance. Concrètement, si vous lui demandez de refactoriser un fichier complexe à 3h du matin sans directives fermes, il vous écrira fièrement : // ... rest of the code here.
La solution ? Des prompts système ultra-structurés, qui imposent un rôle, un format de sortie JSON strict, et surtout, l'obligation de "penser à haute voix". Imposer l'utilisation d'une balise <thought> avant de déclencher une action est primordial pour deux choses : déboguer pourquoi l'agent a pris une mauvaise décision de routage, et améliorer l'UX.
Le Triple-Layer Robust Parsing
Forcer un LLM à répondre en JSON n'est que la moitié du combat. Quand le modèle "fatigue" ou s'emmêle dans le contexte, il peut générer du JSON mal formaté. Pour que l'agent ne plante pas, j'ai dû concevoir un système de parsing à 3 couches :
- Couche 1 : Parsing JSON classique.
- Couche 2 : Fallback Regex pour extraire l'objet si le modèle a rajouté du texte autour.
- Couche 3 : Si le JSON est totalement cassé, un fallback par mots-clés devine l'intention pour une action de repli. Zéro plantage.
Anecdote : Cette approche est née d'un exercice de pensée vers la fin du projet : "Et si on devait faire tourner cet agent sur une machine très modeste avec un SLM (Small Language Model) très instable ?". Les contraintes forcées ont accouché de ces astuces de résilience que j'ai conservées. (Peut-être le point de départ d'un futur "Vibrisse-Lite" ? Affaire à suivre...)
Triple-Layer Retrieval : Un RAG Précis, pas Bruitant
Le RAG n'est pas fait pour gaver le modèle de contexte. Plus vous envoyez de texte à un petit modèle, plus il hallucine. Le contexte doit être ciblé et ultra-précis. L'agent Vibrisse utilise un Triple-Layer Retrieval :
- La Couche Déterministe (Ripgrep) : Pour les requêtes exactes (ex: "Où est définie la variable API_KEY ?"). C'est 100% précis, 0% d'hallucination.
- La Couche Sémantique (ChromaDB) : Pour comprendre l'intention (ex: "Montre-moi comment on gère les erreurs").
- La Couche Statistique (BM25) : Un filet de sécurité classique.
On ne choisit pas une méthode, on exécute les trois et on fusionne les résultats.
Les Muscles de l'Agent : MCP Hub, Web Search et Ghost Mode
Un LLM seul n'est qu'un "cerveau dans un bocal". Il faut bien se rendre compte que pour lui greffer des muscles, la moindre action doit être pensée et codée, ce qui casse vite le côté "magique". Vous voulez que votre agent fasse un simple grep ? Il faut coder l'outil, le tester seul, puis le tester après une action de Vision, puis après une recherche Web, pour s'assurer que LangGraph ne plante pas.
L'agent dispose d'outils locaux, mais aussi d'outils connectés comme la Recherche Web (Tavily API), vitale pour aller chercher la documentation la plus récente avant de répondre.
Le MCP Hub (Model Context Protocol)
Au lieu de réinventer la roue, j'ai intégré le standard MCP d'Anthropic. Vibrisse agit comme un MCP Client. Ajouter un outil revient simplement à brancher un Serveur externe. L'architecture est ainsi "future-proof", prête pour les évolutions comme le webMCP de Google.
Le Ghost Mode : In-File Directives
C'est la killer-feature du workflow. Le but d'un agent n'est pas de vous forcer à discuter dans un chat.
Un WatcherService (basé sur la librairie Python watchdog) tourne en fond. Dès qu'il détecte le tag @vibrisse: dans un commentaire sauvegardé, il déclenche un Ghost Worker silencieux qui génère et injecte le code directement dans l'éditeur.
Le Mode Architecte : Human-in-the-Loop et Artefacts
Pour les tâches complexes, laisser un agent autonome exécuter des dizaines de commandes en boucle est un suicide architectural. Il faut un frein à main. J'ai donc implémenté un pattern Human-in-the-Loop avec LangGraph.
L'interruption de graphe (interrupt_after)
Lorsqu'une tâche structurelle est détectée, le routeur bascule sur un nœud dédié (planning_node). Ce nœud génère un plan d'action formaté en Markdown, enveloppé dans des balises XML strictes (<artifact id="plan">).
La subtilité LangGraph : le graphe est compilé avec l'instruction interrupt_after=["planning_node"]. Dès que le plan est généré, l'exécution s'arrête net côté backend et l'état est sauvegardé en base de données.
Rendu Frontend et Reprise d'État
Côté React, l'UI intercepte ces balises avec une expression régulière, masque le XML brut, et génère un composant interactif riche (un CodeDiff, un diagramme Mermaid, ou un TaskBoard). L'utilisateur a alors des boutons pour "Approuver" ou "Rejeter" la proposition.
Le plus gros piège technique de cette fonctionnalité ? La reprise d'état (Resume).
Quand l'utilisateur clique sur "Approuver", le frontend appelle une route qui relance le graphe LangGraph. Sauf que si on reprend la conversation sans rien dire, le petit LLM se retrouve avec son propre message (AIMessage) en fin d'historique de contexte et se met à halluciner la suite de la discussion.
La solution ingénieuse : Injecter silencieusement un HumanMessage ("Plan approuvé. Tu peux procéder à l'implémentation") dans l'état avant de relancer l'inférence. Le modèle a ainsi une directive claire et sait exactement ce qu'on attend de lui.
Persistance et Limites de Contexte
Guérir l'Amnésie
Un agent qui oublie les décisions prises 2 heures plus tôt est inutile. Vibrisse utilise SQLite pour la persistance complète des threads, couplé à la génération automatique d'un project_map.json à chaque lancement.
L'autre ennemi juré, c'est la limite de la fenêtre de contexte (souvent 8k tokens sur ces petits modèles). Si le RAG ramène trop de fichiers, le contexte explose. Pour gérer cela, Vibrisse surveille en permanence la consommation de tokens et l'affiche en direct dans la Sidebar de l'UI. Le développeur sait ainsi exactement quand le contexte est saturé et qu'il est temps de rafraîchir la conversation.
Sovereign Routing : Déléguer Intelligemment
L'agent analyse la complexité de chaque requête avant d'agir :
- Requête simple -> Modèle local (Ollama). Résultat immédiat.
- Requête complexe -> L'agent propose de basculer sur un modèle Cloud plus puissant, avec le consentement explicite de l'utilisateur.
L'Éléphant dans la Pièce : Latence et RAM
Il faut être honnête sur le principal défaut de l'IA locale : la latence. Combiner une analyse de Vision avec la génération d'un composant React complexe peut prendre jusqu'à 3 minutes (voir plus) sur une machine grand public. C'est le prix à payer pour de la confidentialité totale et du local.
Pour rendre cela gérable, Vibrisse intègre un vrai suivi des ressources matérielles :
- Un check de (V)RAM à l'installation pour configurer finement l'agent via le Wizard d'onboarding.
- Une jauge de ressources dans la Sidebar pour surveiller la charge machine en direct.
- La ThinkingConsole : Le streaming "live" des tokens de pensée. Même quand l'action locale est lente, voir le texte défiler réduit drastiquement la friction cognitive de l'attente. C'est du "Design de vitesse".
La Règle d'Or : Tester par Blocs
Chaque nouvelle feature ajoutée risque de casser une feature existante. Le routeur (qui lit les intentions) est le point le plus capricieux de toute l'architecture. Au moindre ajustement dans la description d'un outil, il peut dérailler. Tout repose sur la sémantique.
La règle absolue : tester, tester, et retester. Même quand on a la flemme. Mais comment tester un système dont les réponses sont aléatoires ?
J'ai mis en place le framework RAGAS (piloté par Llama 3 8B) pour évaluer la qualité et la pertinence du RAG de façon automatisée. À cela s'ajoutent des fichiers de scénarios (tests manuels rigoureux) et des scripts de tests Python légers pour s'assurer que les chaînes de routage ne cassent pas avant d'ajouter le bloc suivant.
Conclusion : L'Éloge du Petit Modèle
Vibrisse n'est pas "le meilleur agent du monde". Il y aura toujours des modèles Cloud plus performants. Mais Vibrisse est la preuve qu'une philosophie Small models, Great tools tient la route en production, à condition d'y mettre la rigueur d'ingénierie nécessaire.
L'outil est open-source. Le code est là.
À vous de jouer :
- Vibrisse Agent sur GitHub
- Le projet est pensé pour être "plug-and-play" avec des scripts d'installation (
install.sh/.bat) pour Mac, Linux et Windows. - Le projet est ouvert aux contributions. Que ce soit pour ajouter un nouveau Worker (un outil MCP), optimiser le système de parsing, ou juste corriger un bug sur le Ghost Mode... Les Pull Requests sont plus que bienvenues ! Venez casser le code et le reconstruire avec moi.
- Si vous deviez construire ou adapter une stack agentique aujourd'hui, quelle est la partie qui vous fait le plus peur à stabiliser ? Le Routing ? Le Parsing ? La gestion du contexte ?
- Dites-le-moi en commentaire.
Fièrement développé à Beauce, au Québec 🇨🇦. Intéressé(e) par la souveraineté locale en IA ? Contactez-nous via Vibrisse Studio !