Dokumentation

Stand: 17. Oktober 2026 · Quelle: doku.html im Repository · GitHub

Ein autonomer Webagent, der zu 100 % im Browser läuft: lokale LLMs auf der GPU (WebGPU), strukturiertes Gedächtnis (AAMS), echte Task-Zerlegung und Ausführung — ohne Cloud, ohne Server.

Was ist das? webgpu-agent ist ein privates Forschungsprojekt / Experiment (WIP) — kein fertiges Produkt, keine Support- oder Stabilitätsversprechen. Es ist ein Prototyp, dessen Zweck es ist, Fragen zu beantworten, die sonst niemand sauber beantwortet: Wie weit kommt ein wirklich autonomer Agent, wenn er komplett im Browser leben muss?

▶ Zur App (Demo) Code auf GitHub (MIT)

1. Warum machen wir das?

1.1 Datensouveränität ist keine Einstellung — es ist die Architektur

Fast alle heutigen AI-Agents arbeiten über Cloud-APIs: Jede Aufgabe, jeder Dateiinhalt, jedes „Gedächtnis" des Agenten läuft über fremde Server. Das ist bequem — aber es bedeutet, dass die Daten nie wirklich uns gehören. Für sensible Inhalte (private Texte, Arbeitsstände, persönliche Notizen) ist das kein vertretbarer Zustand.

webgpu-agent stellt das um: Der Agent läuft komplett im Browser. Es gibt keine Cloud-APIs, kein Backend, keine Serverinfrastruktur. Alle Daten — Aufgaben, Zwischenergebnisse, Audit-Log, Gedächtnis — verbleiben zu 100 % im Client-Browser. Das ist keine Option im Einstellungs-Menü, sondern eine Invariante der Architektur: Sie lässt sich nicht versehentlich „einschalten", weil sie schlicht nicht existiert.

1.2 Lokale Inferenz auf der eigenen GPU

Die Intelligenz kommt nicht aus dem Rechenzentrum, sondern von der GPU des eigenen Geräts. Über WebGPU und WebLLM laufen quantisierte Open-Source-Modelle (Qwen/Llama) direkt im Browser: ein kompakter „Wächter" (0,5 B, läuft permanent) und ein größerer „Planer" (3 B, lädt bei Bedarf nach und wird danach wieder entladen). Damit bleibt alles in einem realistischen VRAM-Budget (Zielprofil: ≤ 4 GB).

1.3 Autonomie im Browser

Ein Agent ist nur dann interessant, wenn er Aufgaben selbst zerlegen und ausführen kann — nicht nur antworten. Deshalb hat das Projekt einen echten Agent-Loop: Der Planer zerlegt eine Aufgabe in Teilaufgaben (fester JSON-Schema), ein Executor führt sie aus, ein Audit-Log dokumentiert jeden Schritt — inkl. echter Token-Usage. Der Agent hat außerdem ein strukturiertes Gedächtnis (Session, Task-Tree, Audit, Memory in IndexedDB) und kann es als JSON exportieren/importieren.

1.4 Die eigentliche Frage: Forschung, nicht Produkt

Dahinter steht eine Forschungsfrage: Wie weit kommt ein autonomer Agent mit echtem Gedächtnis, wenn er vollständig clientseitig leben muss? Wo sind die technischen Grenzen — VRAM, Kontextlänge, WebGPU-Verfügbarkeit, Offline-Fähigkeit, Portabilität des Gedächtnisses? Diese Grenzen wollen wir messen und dokumentieren, nicht behaupten. Deshalb ist das Projekt ausdrücklich ein Experiment: Es gibt ein Benchmark-System, offene Forschungsfragen und einen stufenweisen Plan mit Abbruchkriterien (siehe Forschungsansatz).

1.5 AAMS — Gedächtnis als natives Modell

Das Gedächtnis- und Task-Modell des Agenten ist AAMS (Autonomous Agent Mesh System). Eine Besonderheit dieses Projekts: AAMS spielt doppelt eine Rolle und wird dabei strikt getrennt:

Dasselbe Schema wird in beiden Rollen verwendet, die Instanzen bleiben getrennt. Für den Nutzer heißt das: Der Agent versteht AAMS von Haus aus und baut seine eigene lokale Wissens- und Task-Struktur exakt nach dieser Spezifikation auf.

2. Was ist das Ziel?

2.1 Kernziel

Ein vollständig clientseitiger, autonomer Webagent mit:

• lokaler Inferenz auf der GPU (WebGPU/WebLLM) — keine Cloud für Kernprozesse (Invariante),
• strukturiertem, session-bezogenem Gedächtnis (AAMS-B), portierbar per JSON-Export/Import,
• eigener Task-Zerlegung und -Ausführung (echter Agent-Loop) mit nachvollziehbarer Audit-Spur,
• prüfbar, reproduzierbar und ehrlich dokumentiertem Verhalten (Benchmark-System).

2.2 Forschungsziele (konkret)

2.3 Nicht-Ziele (bewusst)

• Keine Cloud-Anbindung für Kernprozesse, keine automatische Cloud-Synchronisation
• Keine Benutzerverwaltung, kein Multi-Agent-Mesh / WebRTC (spätere, eigene Phase)
• Kein Generalisten-Training, kein Wettlauf mit großen Modellen
• Kein Produkt-Versprechen: Dies ist Forschung — der Stand kann sich ändern, die Richtung bleibt

3. Wo steht das Projekt?

Stand: 17. Oktober 2026 · Prototyp (Vite + TypeScript) · Lizenz: MIT · Mitarbeit willkommen (GitHub-Issues/PRs).

3.1 Umgesetzt

3.2 Noch offen

4. Der Forschungsansatz

4.1 Grundprinzipien

• Messen, nicht raten: Jede Aussage über Besserung braucht einen Benchmark-Vergleich. Keine erfundenen Messwerte.
• Hard DoD: Erfolg ist ein hartes, programmatisch geprüftes 0/1 (z. B. valide JSON ohne Retry), keine „klingt plausibel".
• Strikte Train/Test-Trennung: Auf dem Benchmark trainiert wurde, misst nichts. Test-Szenarien sind zurückgehalten.
• Nur geprüfte Daten: Programmatisch verifizierte Ergebnisse gelten als Beleg — kein Modell bewertet sich selbst.
• Ehrliche Grenzen: Grenzen werden benannt (VRAM, Kontext, Browser), nie still verschwiegen. Ein „nicht möglich" ist ein gültiges Ergebnis.
• Abbruchkriterien: Jeder Forschungsplan hat Stufen mit klaren Abbruch-Bedingungen — auch Abbruch wird dokumentiert.
• Reproduzierbarkeit: Commit-Hash, Modell-Revision, Seed, Tool-Versionen werden festgehalten.
• Lizenz zuerst: Basismodelle, Lehrermodelle und Quellen werden vor Nutzung geprüft.

4.2 Doku-Kette (AAMS-Dev-Prozess, Rolle A)

Der Entwicklungsprozess ist selbst Teil des Experiments: Jede Arbeits-Einheit startet mit einem Workpaper (offen, mit Autor:in und Auftrag), stabil gewordene Wahrheiten steigen in ein Whitepaper auf (mit Decision Records — nachvollziehbare Entscheidungen mit Begründung und Alternativen), und Langzeit-Kontext wird in einem LTM-Index geführt. Die Kette wird nicht übersprungen: Workpaper → Whitepaper → LTM. Das komplette Repo (WORKING/) ist offen einsehbar — man kann also sehen, wie das Projekt entsteht.

4.3 Benchmark-Protokoll (WH-002, Auszug)

Das Benchmark-System definiert eine stabile Level-Achse — die Anzahl der Teilaufgaben und der Charakter steigen mit dem Level:

VRAM-Budget im ≤ 4-GB-Profil (Ground-Truth: WebLLM-Lib-Metadaten):

Gemessen wird pro Lauf (automatisch in das Gedächtnis geloggt): harter DoD (0/1), Score (0–3), geplante Teilaufgaben, echte Token-Usage (Prompt/Completion/Total), Zeit, VRAM (geladen + OOM-Events), Flush-Zyklen und KERN-Integrität (nichts nach einem Kontext-Flush verloren — Invariante). Pass-Regel: 5/5 — und „bewiesen" gilt nur auf dem Referenzgerät (GTX 1050 4 GB, Variante zu verifizieren), nicht auf dem Dev-Gerät (RTX 5090). WebGPU-Determinismus ist nicht garantiert → Läufe werden mehrfach wiederholt und die Streuung angegeben.

4.4 Offene Forschungsfragen (Auswahl)

4.5 Erweiterungs-Proposal (V1–V5, geprüft)

Vorgeschlagene Reihenfolge: V4 → V1 → V5 → V3 → V2 — jede Stufe erst nach menschlicher Freigabe.

5. Offene Probleme — was es zu lösen gilt

Diese Liste ist bewusst gesondert: Hier stehen die Probleme, die wir kennen und die es in Zukunft zu lösen gilt. Bei jedem Punkt steht, warum er wichtig ist und in welche Richtung wir nach besseren Wegen und besseren Lösungen suchen. Die aktuelle Lösung ist bei keinem Punkt als final zu verstehen — genau das ist der Punkt der Forschung.

6. Ein eigenes Modell für den Wächter

Der Wächter ist die permanent geladene Instanz des Agenten (≈945 MB, resident). Er führt die engen Protokoll-Aufgaben aus: Planer-JSON im festen Schema, Tool-Aufruf-JSON, Skill-Routing und Memory-Zusammenfassungen. Genau deshalb ist er der interessanteste Kandidat für ein eigenes, getuntes Modell.

6.1 Der Ansatz

• Ein schmales Modell (0,5–1,5 B), zugeschnitten auf die Protokoll-Aufgaben, das im ≤ 4-GB-VRAM-Profil läuft.
• Hypothese: Ein getunter Spezialist ist in diesen engen, prüfbaren Aufgaben zuverlässiger als das ungetunte Basismodell — bei gleicher Größe. Er ist ausdrücklich kein Generalist.
• Stufenplan mit Abbruchkriterien (0–5), jede Stufe endet mit ehrlicher Auswertung — auch bei Abbruch:

Messgrößen (Base vs. Tuned, identische Bedingungen): Schema-Validität ohne Retry, Tool-Wahl und Parameter korrekt, Retry-Rate, harter DoD-Erfolg, Token/Zeit pro Aufgabe, VRAM-Spitze — und Test-Set-Leistung getrennt von Val-Leistung, damit Überanpassung sichtbar bleibt. „Besser" heißt: Verbesserung außerhalb der Streuung auf dem Test-Split.

6.2 Sinnhaftigkeit & erwarteter Nutzen

• Höhere Zuverlässigkeit genau dort, wo sie am meisten zählt: Der Wächter läuft permanent und ist die „Stimme" des Agenten. Wenn er Planer-JSON und Tool-Aufrufe ohne Retry sauber erzeugt, wird der gesamte Loop stabiler.
• Weniger Retry = weniger Latenz und weniger Token: Jede vermiedene Wiederholung spart Zeit und VRAM-Druck — im 4-GB-Profil ein reales Budget.
• Prüfbar und begrenzt: Die Aufgaben sind eng und programmatisch prüfbar (Schema, DoD). Das macht den Nutzen messbar — im Gegensatz zu vagen „bessere Antworten".
• Ehrliche Einordnung: Ein getunter Wächter wird nicht als „intelligent" beschrieben, sondern als „zuverlässig im Protokoll". Er ersetzt keinen Generalisten — er entlastet ihn.

6.3 Die Probleme (bewusst sichtbar)

7. Links

• App (Demo): Diese App · Space: huggingface.co/spaces/ogerl/webgpu-agent
• Code (MIT): github.com/ogerly/webgpu-agent — inkl. vollständiger Doku-Kette (WORKING/)
• Projekt-Vision (Whitepaper-Quelle): idee.md im Repository
• Beispiel-Projekte des Autors: AAMS · webgpu-arena
• Mitarbeit: Feedback, Issues und Pull Requests sind willkommen — siehe README des Repositories.