pguso/ai-agents-from-scratch: Agenten mit node-llama-cpp selbst bauen

Elf Beispiele statt einer Agentenbibliothek

Das Repository ist kein Werkzeug, das man installiert und aufruft. Es ist eine Abfolge von elf Beispielen, die jeweils in einem eigenen Ordner liegen, mit einer eigenen JavaScript-Datei und zwei Begleittexten: CODE.md erklärt die Umsetzung, CONCEPT.md die dahinterliegende Idee. Die Reihenfolge ist Teil der Methode. Erst ein reiner Prompt-Aufruf, dann Systemprompts, dann Denken, Stapelverarbeitung, Streaming, und ab dem siebten Beispiel Funktionsaufrufe. Wer bei ReAct einsteigt, überspringt genau die Schicht, in der die Entscheidungen des Modells sichtbar werden.

Die Zielgruppe benennt der README selbst: Entwickler, die verstehen wollen, was unter der Haube passiert, bevor sie ein Produktionsframework einsetzen. Der Philosophiesatz des Projekts lautet, man solle durch Bauen lernen und Frameworks erst danach klug einsetzen. Das ist eine didaktische Entscheidung, keine technische. Der Nutzen liegt darin, dass ein Werkzeugaufruf hier nicht als Konfigurationsobjekt erscheint, sondern als Text, den das Modell erzeugt und den der eigene Code auswertet.

Lokale Gewichte als Voraussetzung, nicht als Option

Der gesamte Lernpfad hängt an node-llama-cpp und an Modellgewichten, die im Ordner models/ liegen müssen. Die Einzelheiten stehen laut README in DOWNLOAD.md. Die Anforderungen sind Node.js 18 oder neuer und mindestens 8 GB Arbeitsspeicher, empfohlen werden 16 GB. Das ist die erste harte Grenze des Projekts. Wer auf einem Rechner mit knappem Speicher arbeitet oder in einer Umgebung ohne GPU-nahe Ausführung, wird die späteren Beispiele kaum sinnvoll laufen lassen können.

Der Vorteil dieser Bindung ist die Nachvollziehbarkeit. Es gibt keine Netzwerkschicht zwischen dem eigenen Code und dem Modell, also auch keine versteckte Umschreibung des Prompts durch einen Anbieter. Der Preis ist, dass Modellwahl, Quantisierung und Speicherbedarf zu Themen werden, die man sonst an einen Dienst auslagert. Das Repository behandelt diese Themen nicht als Nebensache: Beispiel zwei ist ein optionaler Ausflug zu gehosteten Modellen, und die zugehörigen Konzepte nennen Netzwerklatenz, Kosten gegen Kontrolle, Datenschutz und Anbieterabhängigkeit. Damit steht der Vergleich zwischen lokal und gehostet ausdrücklich im Lehrplan.

Der Lernpfad in vier Stufen

Die ersten sechs Beispiele bauen keine Agenten. Sie bauen die Grundlagen: Modell laden, Prompt und Antwort, Systemprompt zur Spezialisierung, Reasoning-Aufgaben mit ihren Grenzen, parallele Verarbeitung über Kontextsequenzen, schließlich Streaming mit Token-Budget. Auffällig ist Beispiel vier, das laut Beschreibung ausdrücklich die Grenzen reinen LLM-Denkens zeigt und wann externe Werkzeuge nötig werden. Ein Tutorial, das die Schwäche des eigenen Gegenstands vorführt, bevor es ihn erweitert, ist selten genug.

Ab Beispiel sieben wird aus Textgenerierung Handlungsfähigkeit. Funktionsaufrufe werden eingeführt, Werkzeuge definiert, Parameter über JSON Schema beschrieben. Beispiel acht ergänzt persistenten Zustand über Sitzungen hinweg, mit Fakten, Vorlieben und Abrufstrategien. Beispiel neun bringt das ReAct-Muster mit Zyklus aus Reason, Act und Observe samt Selbstkorrektur. Beispiel zehn geht darüber hinaus zum Atom of Thought: Das Modell erzeugt einen Plan aus atomaren Operationen als strukturiertes JSON, Abhängigkeiten werden aufgelöst, der Plan wird validiert und deterministisch ausgeführt. Beispiel elf schließt mit einer Fehlertaxonomie aus Validierung, LLM, Werkzeugen und Workflow, mit stabilen Fehlercodes, Timeouts und Wiederholungen.

Was das ReAct-Beispiel konkret zeigt

Der ReAct-Agent ist der Punkt, an dem die meisten Frameworks als Blackbox erscheinen. Hier ist der Zyklus offen: Das Modell gibt eine Überlegung aus, wählt ein Werkzeug, der eigene Code führt es aus, das Ergebnis geht als Beobachtung zurück in den Kontext, und die Schleife beginnt erneut. Genau diese Rückkopplung ist der Mechanismus, den man in einer Bibliothek später nicht mehr sieht. Wer ihn einmal selbst geschrieben hat, kann beurteilen, ob ein Framework die Schleife sinnvoll begrenzt oder nur versteckt.

Die Kehrseite ist, dass nichts abgesichert ist. Eine Schleife ohne Abbruchkriterium läuft weiter, und die Frage, wie viele Iterationen ein Plan braucht, beantwortet das Tutorial nicht allgemein. Beispiel elf greift das auf, aber erst am Ende des Pfades. Das ist eine bewusste Reihenfolge: erst verstehen, dann absichern. Für jemanden, der die Beispiele nur kopiert, ist es die falsche Reihenfolge.

Installation und Start

Die Einrichtung besteht aus zwei Schritten. Zuerst die Abhängigkeiten:

npm install

Dann die Modelle, die laut README in den Ordner models/ gehören, mit Einzelheiten in DOWNLOAD.md. Der Aufruf der Beispiele folgt dem Muster:

node intro/intro.js node simple-agent/simple-agent.js node react-agent/react-agent.js

Es gibt keine Konfigurationsdatei mit Schlüsseln, keine Umgebungsvariablen, keinen Server. Jedes Beispiel ist ein eigenständiges Programm, das man direkt startet. Wer den OpenAI-Teil ausprobieren will, braucht zusätzlich einen Zugang zu einem gehosteten Modell, aber dieses Beispiel ist im Lernpfad als optional markiert.

Für die Einordnung hilft die Projektstruktur: Die Ordner im Wurzelverzeichnis heißen wie die Beispiele, die Dateien darin jeweils nach demselben Schema. Die Verweise im README zeigen allerdings auf einen examples/-Pfad, der von den Aufrufbeispielen abweicht. Wer eine Datei nicht findet, sollte sich an der Ordnerstruktur im Repository orientieren, nicht an den Links im Text.

Wo dieses Tutorial nicht hilft

Der Ansatz ist lehrreich und gleichzeitig schlecht skalierbar. Alles läuft in einem Prozess, der ein lokales Modell hält. Es gibt keine Aussage im Material über Nebenläufigkeit über mehrere Prozesse, über Ausfallsicherheit oder über Betrieb auf mehreren Maschinen. Wer einen Agenten für viele gleichzeitige Nutzer braucht, wird die Beispiele umschreiben müssen, und genau dann stellt sich die Frage, warum man nicht von Anfang an ein Framework genommen hat.

Ein zweiter Punkt betrifft die Bewertung. Das Repository liefert keinen Testapparat und keine Messwerte, mit denen sich zwei Agentenarchitekturen vergleichen ließen. Ob der AoT-Agent bei einer konkreten Aufgabe zuverlässiger plant als der ReAct-Agent, lässt sich aus dem Material nicht ableiten. Die Beispiele zeigen Mechanismen, keine Ergebnisse. Wer eine Entscheidung zwischen Architekturen belegen muss, braucht eigene Auswertung.

Schließlich die Sprache: Dies ist die JavaScript-Fassung. Für Python verweist der README auf ein getrenntes Repository. Wer in einer Python-Umgebung arbeitet, sollte dort beginnen, statt die Beispiele zu übersetzen.

Alternative: LangChain und ähnliche Frameworks

Der naheliegende Vergleich ist ein Agentenframework wie LangChain, das Werkzeuge, Speicher und Ketten als fertige Bausteine anbietet. Der Unterschied liegt nicht im Funktionsumfang, sondern im Ort der Entscheidung. Bei einem Framework gibt man Werkzeuge und einen Agententyp an und überlässt die Schleife der Bibliothek. Bei ai-agents-from-scratch schreibt man die Schleife selbst und entscheidet dadurch über Abbruchbedingungen, Kontextfenster und Fehlerbehandlung.

Das ist keine Frage von besser oder schlechter. Ein Framework spart Zeit bei Standardfällen und bringt eigene Abstraktionen mit, die man debuggen muss, wenn etwas nicht funktioniert. Das Tutorial kostet Zeit im Vorfeld und liefert dafür ein mentales Modell, mit dem sich das Verhalten eines Frameworks einordnen lässt. Wer den ReAct-Zyklus einmal von Hand gebaut hat, erkennt in einer Bibliothek sofort, an welcher Stelle sie den Kontext kürzt oder Werkzeugfehler verschluckt.

Wartung, Lizenz und was zu prüfen bleibt

Das Projekt steht unter der MIT-Lizenz. Diese erlaubt Nutzung, Änderung und Weitergabe, auch in proprietären Projekten, verlangt aber die Beibehaltung des Lizenzhinweises und schließt eine Gewährleistung aus. Rechtlich verbindlich ist der Lizenztext selbst, nicht diese Zusammenfassung.

Für die Wartung ist die Bindung an node-llama-cpp der kritische Punkt. Ändert die Bibliothek ihre Schnittstelle, betreffen die Anpassungen jedes der elf Beispiele, weil alle auf derselben Anbindung aufsetzen. Der README nennt keine Versionsangabe für die Abhängigkeit, und es gibt keine veröffentlichten Releases, aus denen sich ein Pflegezyklus ablesen ließe. Wer das Repository als Grundlage für eigenen Code nimmt, sollte die Abhängigkeit selbst festnageln und die Beispiele als Referenz behandeln, nicht als Paket.

Die begleitende Website agentsfromscratch.com ergänzt die Erklärungen, ersetzt aber laut README den Code nicht. Die Arbeitsteilung, die das Projekt vorschlägt, ist klar: das Repository zum Ausführen und Ändern, die Website für Denkmodelle. Wer nur liest, ohne node intro/intro.js auszuführen, verpasst den Teil, um den es eigentlich geht.

Redaktionelles Fazit

Wer verstehen will, was ein Agent tatsächlich tut, arbeitet die elf Beispiele der Reihe nach durch und liest die begleitenden CODE.md- und CONCEPT.md-Dateien. Wer bereits einen Agenten in Produktion betreibt, findet hier wenig Neues, und wer ein fertiges SDK sucht, ist falsch adressiert. Vor dem Start sollte geklärt sein, ob die Maschine die Modelle tragen kann: das Repository nennt mindestens 8 GB RAM, empfiehlt 16 GB, und ohne Modell im Ordner models/ läuft kein einziges Beispiel. Der Prüfpunkt vor dem ersten Commit ist deshalb nicht die Architektur, sondern ob node intro/intro.js auf der eigenen Hardware überhaupt eine Ausgabe erzeugt.

Offizielle Quellen

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