waku-agent : un harness d'agent local où le code reste lisible

Le problème : un agent dont on ne peut pas lire la boucle

La plupart des harness d'agents publient une configuration, pas un mécanisme. On y branche des outils, on empile des abstractions, et la boucle qui décide quoi faire au tour suivant reste hors de portée. waku-agent prend le problème par l'autre bout. Le README annonce une boucle d'environ 95 lignes de Python simple, avec la consigne de la parcourir pas à pas. Le public visé n'est donc pas celui qui veut un assistant clé en main, mais celui qui veut comprendre comment un tour se déroule : quand la mémoire est interrogée, quand un outil est appelé, quand la réponse est produite. Les sujets déclarés du dépôt (agent-framework, llmops, local-first, evals) confirment cette orientation vers des ingénieurs et des personnes qui construisent leur propre outillage plutôt que vers des utilisateurs finaux.

Le deuxième problème visé est la propriété de l'état. La mémoire tient dans un seul fichier SQLite, .waku/state.db, que le README invite explicitement à ouvrir et à lire. Pas de base hébergée, pas de synchronisation opaque : le fichier est sur votre machine. Pour quelqu'un qui refuse de confier l'historique de ses échanges à un service tiers, c'est l'argument central du projet, et il est vérifiable en ouvrant le fichier.

Quatre piliers, et un dashboard qui les rend visibles

Le README résume l'architecture en quatre piliers : harness, loop, memory, eval/LLM-Ops. Le harness est l'enveloppe qui reçoit un message et pilote le tour. La boucle est le cœur : elle décide, appelle, observe, recommence. La mémoire se divise en trois natures, sémantique, épisodique et procédurale, avec deux mécanismes distincts : un gate qui décide s'il faut se souvenir, et une passe qui décide ce qu'il faut conserver. L'évaluation combine des tests déterministes et un juge LLM côte à côte, avec un release gate.

Ce qui distingue ce projet d'un simple exemple pédagogique, c'est le dashboard. Lancé par waku dashboard, il démarre un petit serveur web sur 127.0.0.1, port 7777, sans cloud. Le README précise que le navigateur n'est que l'interface et que le même processus exécute chaque tour. L'onglet Overview affiche le coût, la latence et la répartition entre décisions du gate (retrieve contre skip). L'onglet Loop liste chaque tour avec sa décision de gate, ses appels d'outils, ses tokens et son coût. L'onglet Data propose un navigateur SQLite avec un onglet par table et une console SQL en lecture seule sur state.db. Le frontend est constitué de fichiers statiques, sans étape de build.

Cette transparence a un coût : le dashboard est un composant à maintenir en plus de l'agent, et rien dans le matériel fourni n'indique comment il se comporte quand plusieurs sessions écrivent en parallèle dans le même fichier d'état.

Le gate de mémoire, ou pourquoi tout n'est pas mémorisé

Le détail le plus intéressant du projet est le gate. Le README décrit une décision binaire, retrieve ou skip, prise à chaque tour, et propose un test simple : demander « When am I swimming with Sergey? » puis « what's 12 × 8? ». La première question doit déclencher une récupération en mémoire, la seconde doit l'éviter. L'onglet Ops expose la décision prise tour par tour, et l'onglet Overview agrège la répartition.

C'est une conception défendable. Un agent qui interroge sa mémoire à chaque message paie un coût inutile et risque d'injecter du contexte hors sujet. Un gate ajoute en revanche une source d'erreur : si la décision est prise par le modèle, elle peut être fausse, et une récupération manquée est plus difficile à diagnostiquer qu'un appel d'outil raté. Le README ne détaille pas si le gate est déterministe, appris, ou confié au LLM. C'est une zone d'ombre à vérifier dans le code avant de s'appuyer dessus.

La mémoire sémantique est alimentée par un outil dédié. Le README donne l'exemple « Remember that Raj prefers evening games », qui déclenche save_note, ajoute un fait dans l'onglet Memory ▸ Semantic et met à jour un fichier MEMORY.md. La coexistence d'un fichier SQLite et d'un fichier Markdown pour la même information n'est pas expliquée dans le matériel fourni, et c'est exactement le genre de détail qui compte quand on veut auditer ce que l'agent retient.

Installation : deux chemins, une seule commande

Le README propose deux parcours. Pour exécuter sans lire le code, pip install waku-agent puis waku pour le terminal, ou waku dashboard pour l'interface navigateur. Pour lire le code, ce qui est présenté comme l'intérêt du dépôt, il faut cloner : git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent, puis uv venv && uv pip install -e ., puis cp .env.example .env, puis uv run waku ou uv run waku dashboard. Le README insiste sur un point pratique : uv run waku n'exige aucune activation d'environnement.

Trois modes de lancement sont documentés. uv run waku dashboard pour démarrer sans activation, recommandé. Une activation classique avec source .venv/bin/activate puis waku dashboard. Et uv tool install . pour installer la commande waku globalement. Le README précise que waku et waku dashboard sont deux portes vers le même agent, et que make dashboard fonctionne aussi.

Le choix du fournisseur passe par la variable WAKU_PROVIDER. La liste documentée couvre Anthropic (valeur par défaut), OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter, OpenCode Zen et OpenCode Go. Le README indique qu'un adaptateur d'environ 60 lignes, dans waku/loop/models.py, absorbe les différences entre fournisseurs, avec un seul dialecte dans la boucle. Au premier lancement, l'outil indique quelle clé définir. Pour l'exemple de recherche web multi-outils, il faut une clé TAVILY_API_KEY, à saisir dans l'onglet Connections. Le canal Telegram s'active en définissant TELEGRAM_BOT_TOKEN.

Le cas d'usage qui révèle les limites de la boucle

Le README met en avant un scénario : « Search for the World Cup games still left to play and add each one to my calendar ». Selon la description, l'agent enchaîne plusieurs search_web puis plusieurs create_event, et l'onglet Loop affiche iter 8. C'est présenté comme la démonstration de l'ingénierie de boucle du projet.

Ce même exemple expose la contrainte principale. Huit itérations pour une tâche unique signifient huit appels de modèle, donc un coût et une latence qui croissent avec le nombre d'outils enchaînés. Le dashboard affiche justement ces deux métriques par tour, ce qui laisse penser que les auteurs considèrent la surveillance du coût comme partie intégrante du produit. Il n'en reste pas moins qu'un agent dont la boucle est volontairement minimale n'a pas de garde-fou intégré visible dans le matériel fourni : pas de budget d'itérations mentionné, pas de reprise sur erreur décrite, pas de stratégie de repli quand un appel d'outil échoue au milieu d'une séquence de huit.

Autre limite, plus structurelle. Le projet est local-first, ce qui est un choix, pas une faiblesse. Mais cela signifie qu'il n'y a pas de coordination entre plusieurs machines, pas de file d'attente partagée, pas de montée en charge horizontale. Si votre besoin est un agent qui sert une équipe depuis un service central, ce n'est pas le bon outil. De même, la licence MIT et l'état dans un fichier unique simplifient l'auto-hébergement mais ne règlent pas la question de la sauvegarde : .waku/state.db est un point de défaillance unique, et le README ne décrit aucune procédure de copie ou de migration.

Ce que waku-agent n'essaie pas d'être

La comparaison utile n'est pas avec un framework d'agents générique, mais avec une approche inverse : celle d'un runtime qui prend en charge l'ordonnancement, la persistance et l'observabilité à votre place. Dans ce modèle, on décrit un graphe de nœuds et de transitions, le runtime gère l'état, les reprises et la traçabilité, et l'on n'écrit pas la boucle. Le prix est l'opacité : quand un tour se comporte mal, il faut lire la documentation du runtime plutôt que son propre code.

waku-agent fait le choix inverse et l'assume. La boucle est courte, la mémoire est un fichier que l'on peut ouvrir, et le dashboard sert à voir ce qui se passe plutôt qu'à masquer la mécanique. La contrepartie est que tout ce que le runtime aurait fourni, il faut l'ajouter soi-même : reprise sur erreur, limitation de coût, gestion de concurrence. Le projet a toutefois commencé à combler un écart avec la version v0.1.1, intitulée « agent graphs » : un onglet Graph existe, décrit comme affichant une topologie de triage dessinée depuis le moteur lui-même, avec la porte empruntée par chaque tour. Le README ne détaille pas la syntaxe de définition de ces graphes, et c'est l'un des points à examiner en premier si les workflows conditionnels vous intéressent.

Maintenance, licence et ce qu'il faut vérifier

Le dépôt n'est pas archivé et la dernière poussée date du 29 août 2026. Deux versions sont taguées : v0.1.0 le 26 juillet 2026, présentée comme la première version taguée, et v0.1.1 le 31 juillet 2026, consacrée aux graphes d'agents. L'écart entre les deux est de cinq jours, ce qui indique un rythme de publication rapide à ce stade. Un projet en 0.1.x signifie que les interfaces peuvent changer sans préavis, y compris les clés de configuration et le schéma de state.db. Si vous stockez des données réelles dans ce fichier, prévoyez une procédure de migration avant chaque mise à jour, car le matériel fourni n'en mentionne aucune.

La licence est MIT. Concrètement, cela autorise l'usage commercial, la modification et la redistribution, à condition de conserver l'avis de copyright et le texte de la licence. Le MIT ne fournit aucune garantie et n'engage pas les auteurs en cas de défaut. Ce paragraphe n'est pas un conseil juridique : si vous redistribuez le projet dans un produit, faites relire les mentions de licence par une personne compétente.

Un point de coût mérite attention. Le README liste dix fournisseurs de modèles et un fournisseur de recherche web optionnel. Chaque fournisseur a sa propre tarification, et le projet n'impose rien. Le dashboard affiche le coût par tour, ce qui donne un moyen de mesurer, mais la facture dépend entièrement du modèle que vous choisissez dans WAKU_PROVIDER. Un modèle économique change complètement l'ordre de grandeur du scénario à huit itérations décrit plus haut.

Enfin, le projet s'accompagne d'une chaîne YouTube et de plusieurs réseaux sociaux, et le README mentionne une vidéo de présentation de 20 minutes ainsi qu'un lien de don. Ce n'est pas un défaut en soi, mais cela déplace le centre de gravité de la documentation vers la vidéo. Pour un projet dont l'argument est la lisibilité du code, la documentation écrite disponible ici reste courte sur plusieurs mécanismes centraux : le fonctionnement exact du gate, la relation entre MEMORY.md et la base SQLite, et la syntaxe des graphes introduits en v0.1.1. Ces trois points se vérifient dans le code, pas dans le README.

Conclusion éditoriale

Adoptez waku-agent si vous voulez lire et modifier vous-même la boucle, la mémoire et les evals, et si un fichier SQLite unique comme état vous convient. Passez votre chemin si vous cherchez un runtime distribué, une orchestration multi-agents ou un support éditeur. Avant de vous engager, vérifiez deux choses concrètes : le contenu de .env.example pour le fournisseur que vous utilisez, et la présence du fichier waku/loop/models.py, puisque c'est là que passe l'adaptateur d'environ 60 lignes décrit dans le README.

Sources officielles

1. Issues
2. License: MIT
3. README
4. Releases
5. ShenSeanChen/waku-agent on GitHub