waku-agent: ein Agenten-Harness, dessen Loop rund 95 Zeilen Python umfasst

Welches Problem waku-agent löst und für wen

Die meisten Agentenprojekte verstecken ihre interessanten Teile hinter Abstraktionen. Man installiert ein Paket, konfiguriert einen Provider und bekommt eine Blackbox, in der Loop, Gedächtnis und Auswertung irgendwo im Inneren verschwinden. waku-agent geht den umgekehrten Weg. Das README formuliert es so: "No frameworks hiding the good parts." Der Anspruch ist, dass ein Entwickler den Loop, die Memory-Pillars, die Evals und das Gateway an einem Nachmittag lesen kann.

Die Zielgruppe ist damit enger, als die Beschreibung "personal assistant" vermuten lässt. Es sind Leute, die einen Agenten nicht nur benutzen, sondern verstehen wollen: wie entschieden wird, ob etwas erinnert wird, wie ein Turn durch den Harness fließt, wie ein Eval-Gate einen Release blockiert. Dass das Repository Python, SQLite, LLMOps und evals als Topics führt, passt zu dieser Ausrichtung. Wer dagegen einen fertigen Assistenten für ein Team sucht, findet hier ein Projekt im Zustand v0.1.x mit zwei getaggten Releases.

Ein zweiter Adressat sind Lehrende und Vortragende. Das README verweist auf eine 20-minütige Code-Walkthrough-Videoreihe und ein Architektur-Whiteboard, dessen Boxen laut README jeweils auf eine Datei im Repository zeigen. Das ist ein ungewöhnliches Verkaufsargument für Software: nicht Funktionsumfang, sondern Nachvollziehbarkeit.

Der Loop, das Gate und die vier Pillars

Das README nennt vier Pillars: Harness, Loop, Memory, Eval/LLM-Ops. Der Loop selbst umfasst laut README ungefähr 95 Zeilen Python. Diese Zahl ist die zentrale Designentscheidung. Ein Loop dieser Größe kann keine komplexe Planungslogik enthalten, also muss die Intelligenz woanders sitzen: im Modell, in den Tools und im Gedächtnis.

Das Gedächtnis ist in drei Teile gegliedert: semantisch, episodisch, prozedural. Darüber liegt ein Gate, das entscheidet, ob überhaupt erinnert wird, und ein zweiter Durchgang, der entscheidet, was behalten wird. Das README beschreibt den sichtbaren Effekt an einem Beispiel: Auf "When am I swimming with Sergey?" folgt "what's 12 × 8?", und das Dashboard zeigt, dass der eine Turn den Abruf auslöst und der andere ihn überspringt. Die Gate-Entscheidung pro Turn landet im Ops-Tab.

Die Datenhaltung ist bewusst schlicht. Das Gedächtnis ist eine einzige SQLite-Datei unter .waku/state.db. Das README lädt ausdrücklich dazu ein, sie zu öffnen. Der Data-Tab im Dashboard ist ein SQLite-Browser mit Schema-Ansicht, Tabs pro Tabelle und einer Read-only-SQL-Konsole über genau diese Datei. Ob das Schema dokumentiert ist, geht aus dem Material nicht hervor; die Konsole ist der vorgesehene Weg, es herauszufinden.

Für die Anbindung an Modelle gibt es laut README einen Adapter von etwa 60 Zeilen in waku/loop/models.py. Der Loop spricht einen Dialekt, der Adapter übersetzt. Unterstützt werden Anthropic (Standard), OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter, OpenCode Zen und OpenCode Go. Auswahl über WAKU_PROVIDER. Das ist eine breite Liste für ein Projekt dieser Größe, und sie ist ein Grund, den Adapter als kritische Datei zu behandeln: Jede Provider-Eigenheit muss dort abgefangen werden.

Installation, Dashboard und der Weg zum ersten Turn

Es gibt zwei Wege. Für den schnellen Einstieg nennt das README pip install waku-agent, danach waku für den Terminal-Dialog und waku dashboard für die Browser-Oberfläche auf localhost:7777. Wer den Code lesen will, klont stattdessen:

git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent uv venv && uv pip install -e . cp .env.example .env uv run waku uv run waku dashboard

Das README betont, dass uv run waku keine Aktivierung der virtuellen Umgebung benötigt. Alternativ nennt es source .venv/bin/activate für die Dauer einer Sitzung oder uv tool install . für eine globale Installation des Kommandos. make dashboard funktioniert ebenfalls.

Beim ersten Start teilt das Programm laut README mit, welcher Schlüssel gesetzt werden muss. Die Konfiguration läuft über Umgebungsvariablen: WAKU_PROVIDER für die Auswahl, ein Provider-Schlüssel, TELEGRAM_BOT_TOKEN für den Telegram-Bot. Für die Websuche im World-Cup-Beispiel braucht es zusätzlich einen kostenlosen TAVILY_API_KEY, der laut README im Connections-Bereich eingetragen wird.

Das Dashboard ist ein lokaler Webserver, gebunden an 127.0.0.1. Der Browser ist nur die Oberfläche, derselbe Prozess führt den Turn aus. Das Frontend besteht laut README aus statischen Dateien ohne Build-Schritt. Inhaltlich ist es in Tabs pro Pillar gegliedert: Overview mit Kosten, Latenz und Gate-Verteilung, Gateway mit Nachrichtenherkunft, Loop mit Turns und Tool-Aufrufen, Graph mit Workflow-Topologie, Memory mit Untertabs pro Pillar, Tools mit MCP-Konnektoren, Data mit dem SQLite-Browser und Ops mit Eval-Verdikt, Historie und JSONL-Traces. Ob tatsächlich jeder dieser Tabs im Release v0.1.1 vollständig funktioniert, lässt sich aus dem Material nicht bestätigen.

Ein Turn mit acht Iterationen als Belastungsprobe

Das README empfiehlt ein konkretes Beispiel als Testfall: "Search for the World Cup games still left to play and add each one to my calendar." Der Ablauf ist search_web mehrfach, dann create_event mehrfach, und der Loop-Tab zeigt dabei iter 8. Das ist die ehrlichste Angabe im ganzen README, weil sie eine Zahl für eine reale Aufgabe nennt statt einer Fähigkeit.

Acht Iterationen bedeuten acht Modellaufrufe plus die Tool-Ausführungen. Wer das lokal gegen einen bezahlten Provider fährt, zahlt pro Turn entsprechend. Das Dashboard zeigt genau deshalb Kosten und Token pro Turn im Loop-Tab und aggregiert im Overview. Das ist keine Nebensächlichkeit, sondern die Voraussetzung dafür, solche Mehrfach-Tool-Aufgaben überhaupt verantwortbar zu testen.

Interessant ist auch, was das Beispiel über die Fehlerbehandlung verrät. Eine Suche liefert N Treffer, daraus werden N Kalendereinträge. Was passiert, wenn die Suche beim vierten Aufruf fehlschlägt oder das Modell denselben Termin zweimal bucht, steht nicht im Material. Bei einem Loop von rund 95 Zeilen ist das eine naheliegende Stelle, an der man vor dem ersten echten Einsatz selbst nachliest.

Eval als Release-Gate und die Frage nach der Aussagekraft

Das Projekt bringt zwei Eval-Formen mit: deterministische Tests und LLM-as-judge, laut README Seite an Seite, verbunden mit einem Release-Gate. Der Ops-Tab zeigt das Eval-Verdikt und die Historie. Das ist für ein Projekt dieser Größe ungewöhnlich, weil viele Harnesses die Auswertung dem Nutzer überlassen.

Die Einschränkung liegt in der Natur der Sache. Deterministische Tests prüfen, ob ein Tool aufgerufen wurde oder ob eine Antwort ein Muster enthält. Der LLM-as-judge prüft Qualität, aber mit einem Modell als Bewerter, dessen Urteil selbst schwankt. Das README sagt nicht, welches Modell als Judge dient, ob es dasselbe ist wie das Laufzeitmodell, und wie das Gate bei widersprüchlichen Ergebnissen entscheidet. Wer den Eval-Teil ernst nehmen will, muss diese Fragen im Code klären.

Praktisch relevant ist, dass das Gate an einen Release gebunden ist. Bei zwei getaggten Releases in kurzer Folge, v0.1.0 am 26. Juli und v0.1.1 am 31. Juli, lässt sich aus dem Material nicht ablesen, ob das Gate den zweiten Release tatsächlich blockiert hätte oder ob es zu diesem Zeitpunkt schon aktiv war. Die Release-Notiz zu v0.1.1 lautet lediglich "agent graphs".

Wo waku-agent das falsche Werkzeug ist

Der offensichtlichste Fall sind Teams, die einen Assistenten mit Garantien brauchen: mehrere Nutzer, ein Server, ein Betriebskonzept. waku-agent ist auf einen Rechner und eine Person zugeschnitten. Das Gedächtnis ist eine lokale SQLite-Datei. Das Dashboard ist an 127.0.0.1 gebunden. Es gibt keinen Hinweis auf Mandantentrennung, Rollen oder zentrale Konfiguration. Wer das braucht, ist hier falsch.

Der zweite Fall ist der Wunsch nach einem stabilen Plugin-Ökosystem. Das README erwähnt MCP-Konnektoren im Tools-Tab, aber nicht, wie viele Connectors mitgeliefert werden oder wie deren Lebenszyklus aussieht. Wer auf eine breite Sammlung fertiger Integrationen angewiesen ist, sollte vorher im Repository nachsehen.

Der dritte Fall ist subtiler: Wer den Agenten vor allem wegen der lokalen Datenhaltung wählt, aber ein gehostetes Modell verwendet, verlagert den Inhalt der Gespräche trotzdem zum Provider. Local-first bezieht sich hier auf Speicherung und Ausführung des Harness, nicht auf die Inferenz. Das README formuliert "Nothing leaves your laptop" im Zusammenhang mit dem Dashboard-Prozess, was korrekt ist, aber nicht dasselbe wie vollständig lokale Verarbeitung.

Schließlich die Versionslage. v0.1.0 und v0.1.1 liegen fünf Tage auseinander, das Repository wurde zuletzt am 29. August 2026 aktualisiert. Aus dem Material geht nicht hervor, ob das Projekt aktiv weiterentwickelt wird oder ob es sich um eine abgeschlossene Lehrreihe mit begleitendem Code handelt. Die vielen Video- und Social-Media-Links im README legen nahe, dass der Code Teil eines größeren Lehrformats ist.

Alternative: LangGraph, CrewAI oder ein selbstgebauter Loop

Der naheliegende Vergleich ist LangGraph. Beide modellieren Agenten als Graphen; v0.1.1 von waku-agent trägt die Notiz "agent graphs", und der Graph-Tab zeigt laut README die Triage-Topologie, gezeichnet von der Engine selbst. Der Unterschied liegt im Umfang. LangGraph bringt einen größeren Satz an Primitiven für Zustandsverwaltung, Persistenz und Human-in-the-loop mit, dazu eine umfangreiche Dokumentation und eine breitere Nutzerbasis. waku-agent bringt stattdessen das Gedächtnis mit drei Pillars, ein Gate für die Abrufentscheidung, ein Dashboard und ein Eval-Gate als Teil des Pakets.

CrewAI geht anders vor: Es modelliert mehrere Rollen, die zusammenarbeiten. waku-agent hat einen Assistenten mit einem Loop und vielen Tools. Wer mehrere spezialisierte Agenten braucht, die sich beraten, ist bei CrewAI näher an der Lösung.

Die dritte Alternative ist der eigene Loop. Genau das ist der Punkt, an dem waku-agent am stärksten ist: Es liefert eine Vorlage, die man lesen und dann ersetzen kann. Rund 95 Zeilen Loop und ein Adapter von etwa 60 Zeilen sind kein Framework, das man adoptiert, sondern ein Beispiel, das man kopiert. Wer ohnehin vorhat, den Loop selbst zu schreiben, spart sich mit waku-agent die Recherche zu Provider-Dialekten und Gedächtnisschichten, übernimmt aber auch die Entscheidungen des Autors.

Wartung, Lizenz und was vor dem Einsatz zu klären ist

Die Lizenz ist MIT. Das ist permissiv: Nutzung, Änderung und Weitergabe sind erlaubt, sofern der Copyright-Hinweis und der Lizenztext beibehalten werden. Für ein Projekt, dessen erklärtes Ziel das Lesen und Anpassen des Codes ist, passt das. Wer den Code in ein eigenes Produkt einbaut, sollte dennoch prüfen, ob Abhängigkeiten eigene Lizenzen mitbringen; das Material nennt hierzu nichts. Rechtsberatung ist das nicht.

Die Wartungskosten hängen an drei Stellen. Erstens der Adapter in waku/loop/models.py: Bei zehn genannten Providern und etwa 60 Zeilen bedeutet jeder neue Provider oder jede API-Änderung Arbeit an dieser einen Datei. Zweitens das Schema von .waku/state.db. SQLite-Dateien lassen sich migrieren, aber das Material nennt kein Migrationswerkzeug und keine Schema-Versionierung. Wer ein Gedächtnis über Monate aufbaut, sollte vor einem Upgrade ein Backup der Datei anlegen und den Data-Tab zum Vergleich nutzen. Drittens das Eval-Gate: Es ist nur so nützlich wie die Fälle, die es prüft, und die Pflege dieser Fälle ist laufende Arbeit.

Die Upgrade-Frage lässt sich aus dem Material nicht beantworten. Zwischen v0.1.0 und v0.1.1 liegen fünf Tage und die Notiz "agent graphs". Ob bestehende state.db-Dateien weiterverwendet werden können, sagt das README nicht. Das ist die erste konkrete Sache, die man vor einem produktiven Einsatz klären sollte, und die zweite ist, ob die Eval-Verdikte im Ops-Tab überhaupt aussagekräftige Fälle abdecken.

Redaktionelles Fazit

Wer einen lesbaren Referenzagenten sucht, um Loop, Memory und Eval zu verstehen, und wer bereit ist, den Code selbst zu lesen, findet hier ein MIT-lizenziertes Projekt mit klarer Dateizuordnung. Wer einen betriebsbereiten Assistenten für ein Team braucht, ist hier falsch: zwei getaggte Releases, keine dokumentierte Upgrade-Politik, kein Hinweis auf Migrationswerkzeuge für .waku/state.db. Vor dem Einsatz zu prüfen sind das Verhalten bei Providerwechsel über WAKU_PROVIDER, die Eval-Verdikte im Ops-Tab und ob das Schema von state.db zwischen v0.1.0 und v0.1.1 unverändert bleibt.

Offizielle Quellen

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