Der Agent, den Sie noch nicht kennen: Prinzipien, Architektur und technische Praktiken

0. TL;DR

Nachdem ich „The Claude Code You Don't Know: Architecture, Governance, and Engineering Practices“ geschrieben hatte, wurde mir klar, dass mein Verständnis der zugrunde liegenden Schichten von Agents nicht tief genug war. In Kombination mit der umfangreichen Erfahrung unseres Teams bei der Umsetzung von Agent-basierten Geschäftslösungen verspürte ich das Bedürfnis nach einer systematischen Aufarbeitung. Also habe ich Materialien, Open-Source-Implementierungen und meinen eigenen Code durchgearbeitet, um diesen Artikel zu strukturieren.

Dieser Artikel konzentriert sich auf die Teile der Agent-Architektur, die die größten Auswirkungen auf die Ingenieursergebnisse haben, darunter Kontrollfluss, Kontext-Engineering, Tool-Design, Gedächtnis, Multi-Agent-Organisation, Evaluierung, Tracing und Sicherheit. Abschließend werden wir die OpenClaw-Implementierung nutzen, um diese Designprinzipien zusammenzuführen.

Bei der Aufarbeitung ergaben sich mehrere Schlussfolgerungen, die von meinen ursprünglichen Annahmen abwichen: Die Verbesserungen durch teurere Modelle sind oft geringer als erwartet; stattdessen hat die Qualität des Harness und der Verifikationstests einen größeren Einfluss auf die Erfolgsraten. Beim Debuggen des Agent-Verhaltens sollte man zuerst die Tool-Definitionen überprüfen, da die meisten Tool-Auswahlfehler auf ungenaue Beschreibungen zurückzuführen sind. Darüber hinaus sind Probleme innerhalb des Evaluierungssystems selbst oft schwerer zu erkennen als Agent-Fehler. Wenn man ständig am Agent-Code herumschraubt, ohne Erfolg zu haben, könnte die Antwort in diesen Bereichen liegen.

1. Grundlegende Funktionsweise der Agent-Schleife

Die Kernimplementierungslogik einer Agent-Schleife umfasst, abstrahiert betrachtet, weniger als 20 Codezeilen:

1const messages: MessageParam[] = [{ role: "user", content: userInput }];
2
3while (true) {
4  const response = await client.messages.create({
5    model: "claude-opus-4-6",
6    max_tokens: 8096,
7    tools: toolDefinitions,
8    messages,
9  });
10
11  if (response.stop_reason === "tool_use") {
12    const toolResults = await Promise.all(
13      response.content
14        .filter((b) => b.type === "tool_use")
15        .map(async (b) => ({
16          type: "tool_result" as const,
17          tool_use_id: b.id,
18          content: await executeTool(b.name, b.input),
19        }))
20    );
21    messages.push({ role: "assistant", content: response.content });
22    messages.push({ role: "user", content: toolResults });
23  } else {
24    return response.content.find((b) => b.type === "text")?.text ?? "";
25  }
26}

Der entsprechende Kontrollfluss sieht wie folgt aus: ein kontinuierlicher Kreislauf von Wahrnehmung -> Entscheidung -> Aktion -> Rückmeldung, bis das Modell reinen Text zurückgibt:

Nachdem ich viele Agent-Implementierungen und offizielle SDKs gesehen habe, sind die Strukturen ähnlich. Die Schleife selbst ist recht stabil. Von einer minimalen Implementierung bis hin zur Unterstützung von Sub-Agents, Kontextkomprimierung und Skill-Ladung ändert sich die Hauptschleife selten. Neue Fähigkeiten werden in der Regel außerhalb der Schleife hinzugefügt, anstatt ihr Inneres zu modifizieren.

Neue Fähigkeiten werden hauptsächlich auf drei Arten integriert: Erweiterung von Toolsets und Handlern, Anpassung der System-Prompt-Strukturen und Externalisierung des Zustands in Dateien oder Datenbanken. Der Schleifenkörper sollte keine riesige Zustandsmaschine werden. Das Modell übernimmt das Denken, während externe Systeme den Zustand und die Grenzen verwalten. Sobald diese Arbeitsteilung etabliert ist, muss die Kernschleifenlogik selten häufig angepasst werden.

Was ist der Unterschied zwischen Workflow und Agent?

Anthropic unterscheidet direkt: Ein System, dessen Ausführungspfad im Code vorgegeben ist, ist ein Workflow; ein System, bei dem das LLM dynamisch den nächsten Schritt bestimmt, ist ein Agent. Der Kernunterschied liegt darin, wer die Kontrolle hat. In der Realität sind viele als Agenten bezeichnete Produkte näher an Workflows, aber keines ist von Natur aus überlegen. Entscheidend ist, die richtige Lösung für die Aufgabe zu finden.

In einem Diagramm betrachtet wird es intuitiver:

Fünf gängige Kontrollmuster

Die meisten KI-Systeme sind, wenn man sie zerlegt, Kombinationen dieser fünf Muster. Viele Szenarien benötigen keine vollständige Agenten-Autonomie; die Kombination einiger dieser Muster reicht aus. Der Schlüssel liegt darin, welches Design zur Aufgabe passt.

1. Prompt Chaining: Aufgaben werden in sequenzielle Schritte aufgeteilt, wobei jeder LLM-Schritt die vorherige Ausgabe verarbeitet. Code-Checkpoints können hinzugefügt werden. Geeignet für lineare Prozesse wie Übersetzung nach der Generierung oder das Schreiben des Fließtextes nach einer Gliederung.
2. Routing: Klassifiziert die Eingabe und leitet sie an einen spezialisierten Prozess weiter. Einfache Fragen gehen an leichte Modelle, komplexe an starke Modelle; technischer Support und Abrechnungsanfragen folgen unterschiedlicher Logik.
3. Parallelisierung: Zwei Varianten: Aufteilung (Aufteilung in unabhängige Teilaufgaben) und Voting (mehrmaliges Ausführen derselben Aufgabe zur Konsensfindung). Geeignet für risikoreiche Entscheidungen oder Anforderungen mit mehreren Perspektiven.
4. Orchestrator-Workers: Ein zentrales LLM zerlegt Aufgaben dynamisch und delegiert sie an Worker-LLMs, um dann die Ergebnisse zu synthetisieren. Dies ist der Prototyp für das Spawn-Tool von nanobot und den Sub-Agent-Modus von learn-claude-code.
5. Evaluator-Optimizer: Ein Generator erzeugt eine Ausgabe, und ein Evaluator gibt in einer Schleife Rückmeldung, bis die Standards erfüllt sind. Geeignet für Aufgaben wie Übersetzung oder kreatives Schreiben, bei denen Qualitätsstandards im Code schwer präzise zu definieren sind.

Diese Muster lösen, wie der Kontrollfluss aufgebaut wird. Schauen wir uns nun eine eher technische Frage an: Warum läuft ein System stabil?

2. Warum der Harness kritischer ist als das Modell

Ein Harness bezeichnet die Test-, Verifikations- und Einschränkungsinfrastruktur, die um einen Agenten herum aufgebaut ist. Ein Harness umfasst mindestens vier Teile: Akzeptanz-Baselines, Ausführungsgrenzen, Rückkopplungssignale und Fallback-Methoden.

Während das Modell wichtig ist, bestimmen diese peripheren technischen Bedingungen oft, ob ein System stabil läuft. Diese Einschätzung trifft am meisten auf gut verifizierbare Aufgaben wie das Programmieren zu, aber bei schwach verifizierbaren Aufgaben wie offener Recherche oder mehrrundigen Verhandlungen bleibt die Obergrenze des Modells entscheidender.

OpenAIs Agent-First-Entwicklungspraxis

Drei Ingenieure schrieben in fünf Monaten eine Million Codezeilen mit fast 1.500 PRs – die 10-fache Geschwindigkeit der traditionellen Entwicklung. Diese Geschwindigkeit lag nicht nur an der Stärke des Modells, sondern an den richtigen technischen Entscheidungen:

1. Was der Agent nicht sehen kann, existiert nicht: Wissen muss in der Codebasis selbst vorhanden sein. Externe Dokumente sind für einen laufenden Agenten unsichtbar. AGENTS.md wird auf ~100 Zeilen als Index gehalten, Details werden in docs-Verzeichnisse zur bedarfsgesteuerten Referenz aufgeteilt.
2. Einschränkungen codieren, nicht dokumentieren: Normen in Dokumenten werden leicht ignoriert. In Linter, Typsysteme oder CI-Regeln codierte Einschränkungen sind ausführbar. Die Architekturschichtung wird mechanisch durch benutzerdefinierte Linter erzwungen, nicht durch manuelle Überprüfung.
3. End-to-End autonome Aufgabenerledigung: Von der Überprüfung des Zustands und der Reproduktion von Fehlern über die Implementierung von Korrekturen und die Steuerung der App-Verifikation bis hin zum Öffnen von PRs, der Bearbeitung von Reviews und dem Mergen – die gesamte Kette erfordert keinen menschlichen Eingriff. Agents überprüfen aktiv Logs, Metriken und Traces.
4. Merge-Konflikte minimieren: Behandeln Sie gelegentliche Testfehler mit Wiederholungen, anstatt den Fortschritt zu blockieren. In Umgebungen mit hohem Durchsatz sind die Kosten des Wartens auf manuelle Überprüfung oft höher als die Behebung kleiner Fehler. Die Programmierdisziplin ist nicht verschwunden; sie hat sich von der manuellen Überprüfung zu maschinell ausgeführten Einschränkungen verlagert.

Die App verteilt Logs, Metriken und Traces über Vector an die Victoria-Speicherschicht, die den LogQL-, PromQL- und TraceQL-Schnittstellen entspricht. Codex fragt über diese Schnittstellen ab, korreliert und denkt. Nach Änderungen startet es die App neu, führt Workloads erneut aus und leitet die Ergebnisse an Codex zurück. UI Journeys sind ebenfalls Eingaben. Dieser Observability-Stack wird pro Aufgabe erstellt und nach Abschluss zerstört. Der Agent wartet nicht darauf, über Fehler informiert zu werden; er fragt den Systemzustand ab, um Korrekturen zu verifizieren.

Was ist die wichtigste Schlussfolgerung für den Harness?

Das Diagramm verwendet Aufgabenklarheit und Verifikationsautomatisierung, um Aufgaben in vier Zustände zu unterteilen. Oben rechts (klare Ziele, automatisierte Verifikation) ist die ideale Zone für Agents. Oben links (klare Aufgabe, aber manuelle Überprüfung) wird durch die menschliche Überprüfungsgeschwindigkeit begrenzt. Unten rechts (automatisiertes Feedback, aber vage Ziele) führt zu effizienter Bewegung in die falsche Richtung. Unten links (beides fehlt) macht Agents nutzlos.

Die Aufgabe des Harness ist es, Aufgaben in den oberen rechten Bereich zu verschieben und sicherzustellen, dass richtig und falsch nach maschinell ausführbaren Standards beurteilt werden, nicht nach menschlichen Augen.

3. Warum Kontext-Engineering die Stabilität bestimmt

Die Aufmerksamkeitskomplexität von Transformatoren ist O(n²). Je länger der Kontext, desto leichter können wichtige Signale durch Rauschen verwässert werden. Ein häufiges Fehlermuster ist „Context Rot“, bei dem irrelevanter Inhalt den Kontext dominiert und die Entscheidungsqualität des Agenten nachlässt. Viele Probleme, die wie eine Modellunfähigkeit erscheinen, sind tatsächlich auf eine schlechte Kontextorganisation zurückzuführen.

Warum den Kontext schichten?

Das Problem ist in der Regel nicht, dass das Fenster nicht lang genug ist, sondern dass die Informationsdichte falsch ist. Das jedesmalige Laden selten genutzter Elemente oder das Mischen stabiler Regeln mit dynamischen Zuständen erschwert es dem Modell, das Nützliche zu erkennen.

Die Lösung besteht darin, Informationen nach Häufigkeit und Stabilität zu schichten:

• Permanente Schicht: Identität, Projektkonventionen, absolute Verbote. Inhalte, die für jede Sitzung gelten müssen. Kurz, hart und ausführbar halten.
• Bedarfsgesteuertes Laden: Fähigkeiten und Domänenwissen. Deskriptoren dauerhaft halten, aber den vollständigen Inhalt nur bei Auslösung einfügen.
• Laufzeit-Injektion: Dynamische Informationen wie aktuelle Uhrzeit, Kanal-ID, Benutzerpräferenzen. Werden nach Bedarf pro Runde injiziert.
• Gedächtnisschicht: Sitzungsübergreifende Erfahrungen, die in MEMORY.md geschrieben werden. Nicht direkt im System-Prompt; nur bei Bedarf lesen.
• Systemschicht: Hooks oder Coderegeln für deterministische Logik. Bleibt vollständig außerhalb des Kontexts.

Stecken Sie keine deterministische Logik in den Kontext. Alles, was über Hooks, Coderegeln oder Tool-Einschränkungen ausdrückbar ist, sollte von externen Systemen behandelt werden.

Drei gängige Komprimierungsstrategien

1. Sliding Window: Verwirft alte Nachrichten. Geringe Kosten, verliert aber frühen Kontext. Gut für kurze Chats.
2. LLM Summary: Das Modell erzeugt eine Zusammenfassung. Mittlere Kosten, verliert Details, behält aber Entscheidungen. Gut für lange Aufgaben.
3. Tool Result Replacement: Ersetzt rohe Ausgaben durch Platzhalter. Geringe Kosten, gut für tool-lastige Aufgaben.

Sliding Windows sind am einfachsten, verlieren aber den frühen Hintergrund. Fortgeschrittene LLM-Zusammenfassungen verwenden „Branch Summarization“, die explizit Architekturentscheidungen, unerledigte Aufgaben und wichtige Einschränkungen bewahrt. Beim Tool-Ersatz ersetzt micro_compact alte Tool-Ausgaben in jeder Runde, während auto_compact ausgelöst wird, wenn der Kontext einen Schwellenwert überschreitet.

Prompt Caching zur Reduzierung redundanter Overheads

Die LLM-Inferenz berechnet für jedes Token Key-Value-Paare. Wenn ein Präfix exakt mit einer vorherigen Anfrage übereinstimmt, wird es aus dem Cache gelesen. Caching erfordert eine exakte Präfix-Übereinstimmung. Ein cache-freundliches Design konzentriert sich auf Stabilität: System-Prompts, Tool-Definitionen und lange Dokumente sind stabil und für Caching geeignet. Dynamische Informationen (Zeit, Eingabe, Tool-Ergebnisse) sollten am Ende platziert werden.

Dies hängt mit der Kontextschichtung zusammen. Je stabiler die permanente Schicht, desto höher die Cache-Trefferquote und desto niedriger die Grenzkosten. „Kurz und stabil“ dient nicht nur der Token-Ersparnis; es schützt den Cache. Das verzögerte Laden von Fähigkeiten hilft ebenfalls, indem Inhalte nach dem stabilen Präfix angehängt werden. Ein kontraintuitiver Punkt: Ein stabiler großer System-Prompt kann billiger sein als ein sich häufig ändernder kleiner, da der 90%ige Rabatt auf nachfolgende Lesevorgänge die anfänglichen Schreibkosten überwiegt.

Warum Fähigkeiten bei Bedarf laden?

Fähigkeiten sind ein effektives Muster: Nur den Index im System-Prompt behalten, das vollständige Wissen bei Bedarf laden.

1const systemPrompt = `
2Verfügbare Fähigkeiten:
3- deploy: Vollständiger Produktionsbereitstellungsprozess
4- code-review: Code-Review-Checkliste
5- git-workflow: Branch-Strategie und PR-Normen
6`;
7
8async function executeLoadSkill(name: string): Promise<string> {
9  return fs.readFile(`./skills/${name}.md`, "utf-8");
10}

Fähigkeitsbeschreibungen müssen kurz sein, um eine Token-Aufblähung zu vermeiden, und sollten als Routing-Bedingungen fungieren. Erklären Sie, wann sie verwendet werden sollen, wann NICHT und was die Ausgabe ist. Verwenden Sie „Verwenden bei / Nicht verwenden bei“ mit negativen Beispielen. Viele Routing-Fehler sind auf unklare Grenzen zurückzuführen, nicht auf die Modellfähigkeit. Der System-Prompt sollte die Regeln klarstellen: Vor jeder Antwort available_skills scannen, bei Übereinstimmung die spezifische SKILL.md laden und jeweils nur eine laden.

Die Daten sind klar: Ohne negative Beispiele sinkt die Genauigkeit von 73 % auf 53 %; durch Hinzufügen steigt sie auf 85 % und die Antwortzeit reduziert sich um 18,1 %. Negative Beispiele sind der Schlüssel.

Fähigkeitsdeskriptoren haben zwei Fallstricke. Erstens die Wortanzahl: Lange Beschreibungen für jede Fähigkeit summieren sich. Zweitens die Präzision: „Hilfe bei Backend“ ist zu vage. Effektive Deskriptoren sind Routing-Bedingungen, keine Feature-Einführungen. „Wann man mich verwendet“ ist wichtiger als „Was ich kann“.

Kontrollieren Sie die Menge: Behalten Sie nur hochfrequente Fähigkeiten im permanenten Prompt. Niederfrequente können manuell eingeführt oder als Dokumente behalten werden. Typische Anti-Patterns sind das Stopfen von Hunderten von Zeilen Handbüchern in eine Fähigkeit oder dass eine Fähigkeit zu viele unterschiedliche Aufgaben abdeckt (Review, Deploy, Debug).

Was verliert die Komprimierung am leichtesten?

Das häufigste Problem ist nicht, dass die Zusammenfassung zu lang ist, sondern dass die Behaltenspriorität falsch ist. LLMs löschen oft Informationen, die wiederbeschaffbar erscheinen. Tool-Ausgaben gehen zuerst, aber damit verbundene Architekturentscheidungen und Fehlerpfade verschwinden oft ebenfalls. Definieren Sie explizit Behaltensprioritäten in CLAUDE.md:

1### Kompaktanweisungen: Wie Schlüsselinformationen behalten werden
2Priorität:
31. Architekturentscheidungen (nicht zusammenfassen)
42. Geänderte Dateien und wichtige Änderungen
53. Verifikationsstatus (bestanden/nicht bestanden)
64. Ungelöste TODOs und Rollback-Notizen
75. Tool-Ausgabe (kann gelöscht werden, nur Bestanden/Nicht bestanden-Ergebnis behalten)

Eine weitere Falle: Ändern Sie keine Identifikatoren. UUIDs, Hashes, IPs und Dateinamen müssen exakt erhalten bleiben. Ein falsches Zeichen in einem Commit-Hash zerstört nachfolgende Tool-Aufrufe.

Warum Dateisysteme großartige Kontextschnittstellen sind

Cursor nennt dies „Dynamic Context Discovery“: Standardmäßig weniger geben, bei Bedarf lesen. Dateisysteme sind natürliche Schnittstellen. Tool-Aufrufe geben oft massives JSON zurück; anstatt es in den Kontext zu stopfen, schreiben Sie es in eine Datei. Der Agent kann grep oder rg verwenden, um bei Bedarf zu lesen. Dies hält den Kontext sauber und ist für Entwickler lesbar.

Cursor hat dies mit MCP-Tools verifiziert: Sie synchronisieren Tool-Beschreibungen in Ordner. Agents sehen standardmäßig nur Tool-Namen und fragen bei Bedarf Definitionen ab. In A/B-Tests reduzierte dies den gesamten Token-Verbrauch um 46,9 %.

Dies funktioniert auch für die Komprimierung langer Aufgaben. Anstatt den Verlauf zu verwerfen, speichern Sie das gesamte Chat-Protokoll in einer Datei und referenzieren den Pfad in der Zusammenfassung. Wenn der Agent Details benötigt, kann er sie aus der Datei abrufen, was die Komprimierung zu einem verlustbehafteten, aber nachvollziehbaren Vorgang macht.

4. Tool-Design bestimmt, was ein Agent tun kann

Der Kontext bestimmt, was das Modell sieht; Tools bestimmen, was es tun kann. Qualität übertrifft Quantität. Nur 5 MCP-Server können in Definitionen ~55.000 Token kosten – fast 30 % eines 200K-Kontexts, bevor der Chat überhaupt beginnt. Zu viele Tools verwässern die Aufmerksamkeit des Modells.

Die meisten Tool-Probleme liegen nicht darin, zu wenige zu haben, sondern darin, das falsche auszuwählen, unverständliche Beschreibungen zu haben oder nutzlose Daten zurückzugeben.

Wie sich Tool-Design entwickelt

Das Tool-Design hat drei Phasen durchlaufen. Früher wurden vorhandene APIs einfach als Tools verpackt. Später stellte man fest, dass Auswahlfehler oft darauf zurückzuführen waren, dass Tools für Ingenieure und nicht für Agents entwickelt wurden.

1. Gen: API-Wrapping: Jeder Endpunkt ist ein Tool. Zu granular; Agents müssen mehrere Tools für ein Ziel koordinieren.

2. Gen: ACI (Agent-Computer-Interface): Tools entsprechen Agent-Zielen, nicht Low-Level-APIs. Anstelle von create_file und set_permissions wird create_script(path, content, executable) bereitgestellt.

3. Gen: Fortgeschrittene Tool-Nutzung: Optimierung der Erkennung und des Aufrufs:

• Tool-Suche: Nicht alle Definitionen auf einmal einfügen. Agents finden Definitionen über search_tools. Die Kontexterhaltung erreicht 95 %.
• Programmatischer Tool-Aufruf: Lassen Sie das Modell Code verwenden, um mehrere Aufrufe zu orchestrieren. Zwischenergebnisse bleiben in der Ausführungsumgebung, nicht im LLM-Kontext. Tokens können von 150.000 auf 2.000 sinken.
• Tool-Nutzungsbeispiele: Jedes Tool erhält 1-5 reale Beispiele. JSON Schema beschreibt Typen, aber Beispiele zeigen die Verwendung. Die Genauigkeit kann von 72 % auf 90 % steigen.

ACI-Tool-Designprinzipien

Das Tool-Design wirkt sich direkt auf Agents aus. Es geht nicht nur darum, „ob es aufgerufen werden kann“, sondern „ob es sich selbst korrigieren kann, wenn es falsch aufgerufen wird“.

Schlechtes Design hat vage Parameter und nicht korrigierbare Fehler. Gutes Design verwendet betaZodTool, um Definition und Implementierung zu binden, wobei Zod für Formateinschränkungen und strukturierte Fehlervorschläge verwendet wird:

1const updateTool = betaZodTool({
2  name: "update_yuque_post",
3  description: "Aktualisiert den Inhalt eines Yuque-Beitrags; nicht zum Erstellen neuer Beiträge",
4  inputSchema: z.object({
5    post_id: z.string().describe("Yuque-Beitrags-ID, numerischer String wie '12345678'"),
6    title: z.string().optional().describe("Beitragstitel, weglassen wenn unverändert"),
7    content_markdown: z.string().describe("Markdown-Textkörper"),
8  }),
9  run: async (input) => {
10    const post = await getPost(input.post_id);
11    if (!post) throw new ToolError("Beitrags-ID existiert nicht", {
12      error_code: "POST_NOT_FOUND",
13      suggestion: "Rufen Sie zuerst list_yuque_posts auf, um eine gültige post_id zu erhalten",
14    });
15    return await updatePost(input.post_id, input.title, input.content_markdown);
16  },
17});

Schlechtes Design sagt nur, was es tut, nicht, wann es verwendet werden soll. Gutes ACI-Design hat klare Grenzen und strukturierte Fehler, die Agents helfen, richtig zu wählen und Fehler schnell zu beheben. Debuggen Sie zuerst die Tools; die meisten Fehler liegen in den Beschreibungen, nicht in der Modellfähigkeit.

Warum Tool-Nachrichten isolieren?

Frameworks generieren interne Ereignisse (Komprimierung, Benachrichtigungen). Diese sollten im Sitzungsverlauf sein, aber nicht an das LLM gesendet werden, da sie Tokens verschwenden und das Modell verwirren. Die Lösung sind zwei Nachrichtentypen: AgentMessage für die App-Ebene (mit benutzerdefinierten Feldern) und standardmäßige Message (user, assistant, tool_result) für das LLM.

5. Entwerfen des Gedächtnissystems

Agents fehlt die natürliche zeitliche Kontinuität. Der Kontext wird nach einer Sitzung gelöscht. Um eine sitzungsübergreifende Konsistenz zu erreichen, muss eine Gedächtnisschicht als Infrastruktur entworfen werden, nicht als nachträglicher Einfall.

Wo leben die vier Gedächtnistypen?

Kategorisiert nach dem Problem, das sie lösen:

• Kontextfenster (Arbeitsgedächtnis): Minimale Informationen für die aktuelle Aufgabe. Begrenzte Tokens; muss verwaltet werden.
• Fähigkeiten (Prozedurales Gedächtnis): Wie man Dinge tut (Workflows, Normen). Bei Bedarf geladen.
• JSONL-Sitzungsverlauf (Episodisches Gedächtnis): Was passiert ist. Auf der Festplatte gespeichert; durchsuchbar.
• MEMORY.md (Semantisches Gedächtnis): Stabile Fakten, die vom Agenten geschrieben wurden. In System-Prompts injiziert.

Wie MEMORY.md und Fähigkeiten zusammenarbeiten

Der Kern besteht darin, wichtige Fakten zu behalten und gleichzeitig die Inhaltsmenge zu kontrollieren.

ChatGPTs 4-Schichten-Gedächtnis: Einfache Struktur. Sitzungsmetadaten (nicht gespeichert), Benutzergedächtnis (~33 Fakten, gespeichert/injiziert), Gesprächszusammenfassung (~15 aktuelle Zusammenfassungen, gespeichert), Aktuelle Sitzung (Sliding Window).

OpenClaw Hybrid Retrieval: Tägliche Logs (memory/YYYY-MM-DD.md), MEMORY.md für kuratierte Fakten und memory_search unter Verwendung von hybridem Retrieval (70 % Vektorähnlichkeit + 30 % Schlüsselwort). Für die meisten Agents sind strukturiertes Markdown + Schlüsselwortsuche für Debuggbarkeit und Kosten ausreichend.

Auslösen und Rückgängigmachen der Gedächtniskonsolidierung

Wenn tokenUsage / maxTokens >= 0,5, Konsolidierung auslösen. Nachrichten zusammenfassen, an MEMORY.md anhängen und den Index aktualisieren. Bei Fehlschlag rohe Nachrichten in ein Archiv schreiben. Der Prozess muss umkehrbar sein; Zeiger verschieben, keine Rohdaten löschen.

6. Schrittweise Erhöhung der Agenten-Autonomie

Autonomie erfordert drei Infrastrukturteile: sitzungsübergreifende Wiederaufnahme, Fortschrittseinschränkungen innerhalb der Sitzung und Hintergrund-I/O für langsame Aufgaben.

Wie man lange Aufgaben sitzungsübergreifend fortsetzt

Lange Aufgaben schlagen fehl, wenn Sitzungen vor Abschluss enden. Ein stabiler Ansatz verwendet einen Initialisierungs-Agenten und einen Codierungs-Agenten. Der Initialisierer wird einmal ausgeführt, um feature-list.json, init.sh und claude-progress.txt zu erstellen. Der Codierungs-Agent läuft dann in mehreren Sitzungen, nimmt von diesen Dateien wieder auf, implementiert ein Feature, führt Tests aus und aktualisiert die Fortschrittsdatei. Dies macht die Aufgabe zu einem externen Zustand.

Halten Sie den Fortschritt in Dateien, nicht im Kontext. Verwenden Sie JSON für die Struktur. Die Aufgabe ist erst abgeschlossen, wenn alle Features in feature-list.json passes: true sind.

Warum den Aufgabenstatus explizit schreiben?

Ohne externe Anker treiben Agents ab oder beenden vorzeitig. Zeichnen Sie den Status als externes Kontrollobjekt auf:

1{
2  "tasks": [
3    {"id": "1", "desc": "Konfiguration lesen", "status": "completed"},
4    {"id": "2", "desc": "Schema ändern", "status": "in_progress"}
5  ]
6}

Einschränkung: jeweils nur ein in_progress. Status nach jedem Schritt aktualisieren.

Integration von Hintergrund-I/O

Langsame I/O (Dateioperationen, Netzwerk) sollte die Hauptschleife nicht blockieren. Legen Sie langsame Unterprozesse in Hintergrund-Threads und injizieren Sie Ergebnisse über eine Benachrichtigungswarteschlange vor dem nächsten LLM-Aufruf. Dies ist wartbarer als eine komplexe asynchrone Laufzeitumgebung.

7. Organisation von Multi-Agent-Systemen

Das Engineering von Multi-Agent-Systemen dreht sich um Isolation und Zusammenarbeit.

Director-Modus: Synchron. Mensch interagiert eng mit einem Agenten. Kontext geht verloren, wenn die Sitzung endet.

Koordinator-Modus: Asynchrone Delegation. Mensch setzt Ziele, Agents arbeiten parallel, Mensch überprüft die Ausgabe. Die Ausgabe wird zu persistenten Artefakten (PRs, Branches).

Ein Orchestrator verwaltet Sub-Agents, die parallel arbeiten, über JSONL-Inbox-Protokolle kommunizieren und Worktrees zur Isolation verwenden.

Wofür sind Sub-Agents gut?

Suche und Trial-and-Error sollten den Kontext des Haupt-Agenten nicht verschmutzen. Der Haupt-Agent benötigt nur die Schlussfolgerung.

1const result = await runAgentLoop(task, { messages: [] });
2return summarize(result); // Hauptkontext sieht nur diese Zeile

Warum Zusammenarbeit als Protokoll schreiben?

Zusammenarbeit in natürlicher Sprache scheitert, wenn Agents Versprechen vergessen. Verwenden Sie ein strukturiertes Protokoll:

1{ request_id, from_agent, to_agent, content, status: 'pending', timestamp }

Verwenden Sie ein append-only JSONL-Inbox für die Crash-Wiederherstellung. Zuerst Isolation, dann Zusammenarbeit.

Halluzinationen verstärken sich in Multi-Agent-Systemen

Fehler kaskadieren zwischen Agents. Cross-Validation unterbricht diese Kette, indem ein unabhängiger Agent oder externes Feedback (Tests, Compiler) die Schlussfolgerung beurteilt.

8. Wie man Agents evaluiert

Evaluierung erfordert Testfälle, Bewertungsstandards und automatisierte Verifikation.

Traditionelle Single-Turn-Evaluierung (Prompt -> Antwort) ist unzureichend. Agent-Evaluierung erfordert Tools und Umgebungen. Die Bewertung basiert darauf, was in der Umgebung passiert ist, nicht nur darauf, was der Agent gesagt hat.

Schlüsselkonzepte: Aufgabe, Durchlauf, Bewerter. Transkript (Ausführungsprotokoll) vs. Ergebnis (Endzustand). Sie benötigen beides. Ein Agent könnte sagen „Ticket gebucht“ (Transkript), aber es versäumen, den Datenbankeintrag zu erstellen (Ergebnis).

Evaluationsstatus und Metriken

Viele Teams verlassen sich immer noch auf manuelle Überprüfung oder LLM-Richter. Übliche Metriken: Pass@k (kann es theoretisch funktionieren?) und Pass^k (ist es stabil für die Produktion?). Vermische sie nicht.

Drei Arten von Bewertern

1. Code-Bewerter: Zeichenkettenabgleich, Unit-Tests. Höchste Sicherheit.
2. Modell-Bewerter: LLM-Richter basierend auf Kriterien. Gut für semantische Qualität.
3. Menschliche Bewerter: Expertenüberprüfung. Langsam, legt aber die Basis fest.

Aufbau eines Evaluierungssystems von Grund auf

Beginne mit 20-50 echten Fehlerfällen. Stelle sicher, dass die Umgebung isoliert ist, damit sich Tests nicht gegenseitig beeinflussen. Beziehe sowohl positive als auch negative Fälle ein. Wenn zwei Experten sich bei einem Fall uneinig sind, sind die Kriterien noch nicht klar.

Repariere die Evaluierung, bevor du den Agenten reparierst

Wenn die Werte sinken, überprüfe zuerst das Evaluierungssystem. Umgebungsprobleme (Speichergrenzen, Fehler in Bewertern) sehen aus wie Modellverschlechterung.

9. Nachverfolgung des Ausführungsprozesses

Ohne Ablaufverfolgungen können Fehler nicht reproduziert werden. APM-Metriken (Latenz, Fehlerrate) reichen nicht aus; du brauchst die Argumentationskette.

Was in einer Ablaufverfolgung aufgezeichnet werden sollte?

Vollständiger Prompt, Nachrichten über mehrere Runden, Tool-Aufrufe/Argumente/Rückgaben, Denkkette, endgültige Ausgabe, Tokens und Latenz.

Zweischichtige Beobachtbarkeit

1. Manuelles Sampling: Regelbasiertes Sampling von Fehlern oder negativem Feedback, um Fehlermuster zu finden.
2. LLM-Auto-Evaluierung: Vollständige Abdeckung der Ablaufverfolgungen unter Verwendung der manuellen Schicht als Kalibrierungsbasislinie.

Ereignisströme als Grundlage

Emittere Ereignisse bei tool_start, tool_end und turn_end. Nachgelagerte Systeme (Logs, UI, Evaluierung) verbrauchen diese Ereignisse, ohne den Kernschleifencode zu ändern.

10. Auslieferung von Agenten mit OpenClaw

OpenClaw verwendet fünf entkoppelte Schichten: Gateway, Kanaladapter, Pi-Agent (Kernschleife), Toolsets (ACI-Design) und Kontext/Gedächtnis.

Entkopplung des Nachrichtenbus

Ein Nachrichtenbus trennt Kanäle vom Agenten. Kanäle kümmern sich nur um I/O; der Agent kümmert sich nur um die Verarbeitung.

System-Prompts in Schichten

SOUL.md definiert Identität und Abschlussstandards. Prompts sind geschichtet: Laufzeitinformationen -> Identität -> Gedächtnis -> Fähigkeiten -> dynamische Injektion.

Sicherheitsgrenzen zuerst

Bevor du Funktionen hinzufügst, richte ein: Benutzer-Whitelists, Arbeitsbereichsisolierung (Pfadprüfungen) und Audit-Logs.

Prompt-Injection-Schutz: Behandle externe Inhalte als nicht vertrauenswürdig. Verwende Quell-Senke-Trennung. Gib Agenten keine Werkzeuge, die sie nicht brauchen. Fordere explizite menschliche Bestätigung für sensible Aktionen.

Provider-Fallback: Wechsle automatisch den Anbieter (Anthropic -> OpenAI), wenn einer ausfällt.

11. Häufige Anti-Patterns

1. System-Prompt als Wissensdatenbank (zu lang).
2. Werkzeugwucher (Agent wählt falsche Werkzeuge).
3. Fehlende Überprüfungsschleifen.
4. Multi-Agenten-Systeme ohne Grenzen.
5. Keine Gedächtniskonsolidierung (Qualität sinkt nach 20 Runden).
6. Kein Evaluierungssystem.
7. Vorzeitige Multi-Agenten-Komplexität.
8. Sich auf Erwartungen statt auf mechanische Einschränkungen verlassen.

12. Fazit

1. Der Agentenkern ist eine stabile Schleife; neue Funktionen sollten externalisiert werden.
2. Das Harness bestimmt die Konvergenz mehr als das Modell.
3. Kontext-Engineering verhindert „Context Rot“.
4. ACI-Werkzeugdesign konzentriert sich auf Ziele und Fehlerkorrektur.
5. Gedächtnis ist geschichtet (Arbeits-, Prozedurales, Episodisches, Semantisches).
6. Lange Aufgaben verlassen sich auf externalisierten Zustand und Dateien.
7. Multi-Agenten-Systeme benötigen Protokolle und Isolation.
8. Evaluierung Pass@k für Fähigkeit, Pass^k für Qualität.
9. Ablaufverfolgung ist die Voraussetzung für das Debugging.
10. Stabile Agenten verlassen sich auf technische Details wie Entkopplung und Sicherheitsgrenzen.