pguso/ai-agents-from-scratch : construire un agent LLM local sans framework, exemple par exemple

Le problème visé : comprendre l'agent avant d'importer une bibliothèque

La plupart des projets qui manipulent des agents commencent par une dépendance. On installe un framework, on déclare un outil, et le cycle raisonnement-action se déroule dans du code qu'on n'a pas écrit. pguso/ai-agents-from-scratch prend le chemin inverse. Le README annonce la philosophie en une ligne : « Learn by building. Understand deeply, then use frameworks wisely. » Le public visé est donc précis : un développeur qui sait déjà écrire du JavaScript et qui veut voir, fichier par fichier, ce qu'un appel de fonction déclenché par un LLM implique réellement. Le dépôt se présente comme un tutoriel, pas comme une bibliothèque. Il n'expose pas d'API à importer dans vos propres projets, et rien dans le matériel fourni ne suggère le contraire. Le choix du LLM local renforce cette intention : avec node-llama-cpp, l'inférence se passe sur votre machine, ce qui supprime la clé d'API et rend le comportement du modèle observable sans facturation à la requête. Une version Python du même parcours existe, hébergée séparément sous pguso/agents-from-scratch, ce qui indique que la progression pédagogique est considérée comme indépendante du langage.

Onze étapes, du prompt brut au planificateur AoT

Le parcours est numéroté et le README insiste pour qu'on le suive dans l'ordre. Les sept premiers exemples construisent les briques : intro/ pour le cycle prompt-réponse et le chargement du modèle, openai-intro/ en option pour comparer avec un modèle hébergé, translation/ pour les prompts système et la spécialisation, think/ pour le raisonnement et ses limites, batch/ pour le traitement concurrent via des séquences de contexte, coding/ pour le streaming token par token, puis simple-agent/ où le function calling fait basculer la génération de texte vers l'action. Viennent ensuite simple-agent-with-memory/ pour la persistance entre sessions, react-agent/ pour la boucle Raisonner, Agir, Observer, aot-agent/ pour la planification par atomes de pensée avec dépendances entre opérations, et error-handling/ pour une taxonomie d'erreurs typées. Chaque dossier possède, d'après l'arborescence décrite, un CODE.md et un CONCEPT.md en plus du script exécutable. Cette séparation est l'élément le plus intéressant du dépôt : le code se lit seul, l'explication du mécanisme vit à côté, et le lecteur peut comparer ce qu'il croyait comprendre avec ce que le fichier de concepts énonce. Le README qualifie d'ailleurs simple-agent/ de point où « text generation becomes agency », ce qui situe clairement la charnière pédagogique.

Le mécanisme : des scripts Node.js qui pilotent node-llama-cpp

L'architecture visible dans le matériel est volontairement plate. Pas de routeur, pas de graphe d'exécution, pas de couche de sérialisation : un script par concept, exécuté directement avec node. Le flux de données suit toujours la même direction. Le script charge un modèle local placé dans ./models/, construit un contexte, envoie un prompt, lit la réponse. Dans simple-agent/, cette boucle s'enrichit : des outils sont décrits au modèle, leurs paramètres le sont en JSON Schema, et le modèle choisit d'appeler ou non. Dans react-agent/, la sortie du modèle est réinjectée comme observation dans le contexte, et le cycle recommence jusqu'à résolution. Dans aot-agent/, le modèle produit un plan structuré en JSON composé d'opérations atomiques avec leurs dépendances, puis ce plan est exécuté de façon déterministe. Cette dernière étape est la plus instructive sur le plan architectural : elle sépare la phase où le modèle raisonne de la phase où le code agit, ce qui réduit la surface où une hallucination peut produire un effet. Le README mentionne aussi batch/ et ses « context sequences » pour paralléliser, un point qui touche directement à la consommation mémoire du moteur d'inférence.

Mise en route : deux commandes et un dossier de modèles

L'installation tient en une ligne : npm install. Les prérequis annoncés sont Node.js 18 ou plus, au moins 8 Go de RAM avec 16 Go recommandés, et un modèle téléchargé puis déposé dans ./models/. Le README renvoie à DOWNLOAD.md pour les détails, et c'est un point à ne pas survoler : le nom et le format du fichier attendu déterminent si les scripts trouvent le modèle au premier lancement. Une fois le modèle en place, l'exécution se fait script par script : node intro/intro.js, node simple-agent/simple-agent.js, node react-agent/react-agent.js. Il n'y a ni serveur à démarrer, ni variable d'environnement obligatoire pour le chemin local, ni fichier de configuration global décrit dans le matériel fourni. L'exemple openai-intro/ fait exception puisqu'il cible un modèle hébergé, et le README le marque explicitement comme optionnel. Cette simplicité d'exécution est cohérente avec l'objectif : chaque fichier reste lisible d'un bout à l'autre, et l'ajout d'un outil se fait en modifiant le script concerné plutôt qu'en éditant un manifeste.

Ce que le dépôt ne fera pas pour vous

Le matériel fourni ne décrit ni serveur HTTP, ni interface de ligne de commande générique, ni bibliothèque publiée sur npm. Rien n'indique qu'un paquet soit distribué, et il n'y a aucune release récupérée. Autrement dit, vous ne pouvez pas installer ce dépôt comme dépendance : vous clonez, vous lisez, vous exécutez. La contrainte matérielle est réelle également. Un modèle local qui tient dans 8 Go de RAM reste un petit modèle, et la qualité du function calling dépend fortement de cette taille. Le README présente d'ailleurs think/ comme l'occasion d'observer « limitations of pure LLM reasoning » et de comprendre quand un outil externe devient nécessaire, ce qui revient à admettre que le modèle seul ne suffit pas sur les tâches quantitatives. Le choix du local a un coût : pas de facturation à la requête, mais une latence et une empreinte mémoire qui vous appartiennent. Enfin, le dépôt est un tutoriel dont la valeur tient à la progression. Si vous cherchez uniquement un agent ReAct fonctionnel, vous devrez quand même traverser les exemples précédents ou extraire le fichier qui vous intéresse, et rien ne garantit que ce fichier soit réutilisable hors de son contexte pédagogique.

Face à LangChain : le cycle explicite contre l'orchestration fournie

La comparaison utile n'est pas technique mais pédagogique. Un framework comme LangChain fournit des abstractions prêtes à l'emploi pour les outils, la mémoire et les boucles d'agent. Vous écrivez moins de code, et vous héritez aussi de choix que vous n'avez pas faits : comment un outil est sélectionné, comment l'historique est tronqué, comment une erreur d'outil remonte. pguso/ai-agents-from-scratch fait l'inverse. Le dépôt vous oblige à écrire la boucle ReAct vous-même, à définir le schéma JSON de chaque outil, à décider ce qui entre dans le contexte et ce qui en sort. Le README formule l'objectif ainsi : comprendre « why frameworks make certain design choices ». C'est un argument défendable, à condition d'accepter le coût. Après ce parcours, vous lirez le code d'un framework avec un œil différent, mais vous n'aurez rien à déployer. L'inverse est vrai aussi : quelqu'un qui a déjà écrit plusieurs agents en production n'apprendra probablement pas grand-chose des premiers exemples, et devra aller directement vers aot-agent/ et error-handling/ pour trouver de la matière.

Maintenance, licence et coût de suivi

Le dépôt est publié sous licence MIT, ce qui autorise la réutilisation, la modification et la redistribution du code, y compris dans un contexte commercial, à condition de conserver l'avis de licence. Ce n'est pas un avis juridique : si vous reprenez des extraits dans un produit, faites vérifier les mentions par qui de droit. Le coût de maintenance dépend surtout de node-llama-cpp, qui lie le dépôt à l'évolution des formats de modèles et des API du moteur d'inférence. Une mise à jour majeure de cette dépendance peut rendre un exemple obsolète sans que le code pédagogique ait changé. Le dépôt n'est pas archivé et le dernier push est daté du 24 juillet 2026, ce qui indique une activité, mais l'absence de release récupérée signifie qu'il n'existe pas de version étiquetée sur laquelle se figer. Pour un usage d'apprentissage, ce n'est pas un problème. Pour un usage répété en équipe, cela veut dire épingler vous-même une révision et surveiller les changements de node-llama-cpp de votre côté.

Conclusion éditoriale

Ce dépôt convient à un développeur Node.js qui veut voir le cycle complet d'un agent avant d'adopter LangChain ou un équivalent, et qui accepte de télécharger un modèle GGUF et de disposer de 8 Go de RAM au minimum. Il ne convient pas à qui cherche un composant à mettre en production : aucun paquet publiable, aucun serveur, aucun test de charge. Avant de vous engager, vérifiez deux choses concrètes : que le fichier de modèle attendu se place bien dans ./models/ selon DOWNLOAD.md, et que l'exemple 11 sur la gestion d'erreurs couvre le mode de défaillance qui vous concerne, car c'est là que se joue la différence entre une démo et un système qui tient.

Sources officielles

1. Issues
2. License: MIT
3. pguso/ai-agents-from-scratch on GitHub
4. README