Harness Engineering: So bauen Sie KI-Agenten, die wirklich funktionieren

Die meisten versuchen, KI-Agenten auf der falschen Ebene zu reparieren.

Wenn ein Agent scheitert, schreiben sie den Prompt um. Scheitert er erneut, fügen sie weitere Anweisungen hinzu, wechseln das Modell, vergrößern das Kontextfenster oder binden ein anderes Tool an.

Und dann kehren dieselben Probleme zurück.

Der Agent vergisst eine wichtige Entscheidung. Er nutzt das falsche Tool. Er verliert den Überblick darüber, was drei Schritte zuvor passiert ist. Er behauptet, die Aufgabe sei erledigt, ohne das Ergebnis zu prüfen. Er wiederholt dieselbe fehlgeschlagene Aktion so lange, bis das Budget aufgebraucht ist.

Das Problem liegt nicht immer am Modell.

Das Problem ist die Umgebung rund um das Modell.

Diese Umgebung ist der Harness.

Harness Engineering ist die Praxis, das System um ein Modell herum so aufzubauen, dass es bestimmt, was das Modell sehen kann, was es tun darf, woran es sich erinnert, was als Erfolg gilt und was bei einem Fehler passiert.

Ein besserer Prompt kann eine einzelne Antwort verbessern.

Ein besserer Harness verbessert jeden einzelnen Durchlauf.

Folge mir auf Substack für mehr praxisnahe Analysen zu KI-Agenten, Automatisierung und Produktivsystemen:

substack.com/@lunarresearcher

1. Das Modell ist nicht der Agent

Ein Modell kann schlussfolgern, generieren, vergleichen und auswählen.

Das macht es noch nicht zu einem zuverlässigen Agenten.

Ein echter Agent muss außerdem den richtigen Kontext finden, Tools nutzen, Zustände erhalten, Berechtigungen respektieren, seine eigene Arbeit überprüfen und sich erholen, wenn sich die Umgebung anders verhält als erwartet.

Das Modell ist nur die Denkmaschine.

Der Harness ist alles, was dieses Denken in echte Ausführung verwandelt.

1BENUTZERANFRAGE
2      |
3      v
4+-----------------------------+
5|           HARNESS           |
6|                             |
7| Vertrag       Kontext       |
8| Tools         Zustand       |
9| Richtlinie    Verifizierung |
10| Traces        Wiederherst.  |
11+-----------------------------+
12      |
13      v
14    MODELL
15      |
16      v
17REALE UMGEBUNG

Steck dasselbe Modell in eine Chatbox, und es beantwortet Fragen.

Steck es in ein Repository mit Terminalzugriff, Tests, Browser-Tools, Projektgedächtnis, kontrollierten Berechtigungen und einer Review-Schleife – und es kann echte Arbeit erledigen.

Das Modell hat sich nicht verändert.

Der Harness schon.

2. Mach aus jeder Anfrage einen Vertrag

Natürliche Sprache ist flexibel.

Autonome Ausführung sollte das nicht sein.

Eine Anfrage wie:

Verbessere den Onboarding-Prozess.

ist völlig in Ordnung, solange ein Mensch neben dem Modell sitzt.

Als Produktionsanweisung ist sie katastrophal.

Bevor der Agent handelt, solltest du die Anfrage in einen klar abgegrenzten Aufgabenvertrag verwandeln.

1objective: Abbruchrate beim Onboarding senken
2
3inputs:
4  - Produktbeschreibung
5  - Analytics-Daten
6  - Repository
7
8constraints:
9  - Authentifizierung beibehalten
10  - Datenbankschema nicht ändern
11  - aktuelles Verhalten auf Mobilgeräten beibehalten
12
13deliverable:
14  - überprüfbarer Pull Request
15
16done_when:
17  - Tests bestehen
18  - Analytics-Event wird korrekt ausgelöst
19  - Desktop-Ablauf besteht die Prüfung
20  - Mobile-Ablauf besteht die Prüfung
21
22approval_required:
23  - Deployment in Produktion

Der entscheidende Teil ist done_when.

Ohne ihn kann der Agent eine etwas einfachere Version des Problems lösen und trotzdem voller Überzeugung behaupten, die Aufgabe sei erledigt.

Mit ihm wird der Abschluss messbar.

Der Agent sollte nicht fragen:

Was soll ich als Nächstes tun?

Er sollte fragen:

Welche Aktion bringt die aktuelle Umgebung näher an das vertraglich vereinbarte Ergebnis?

Das ergibt eine deutlich stärkere Schleife.

3. Gib dem Agenten eine Karte, kein riesiges Kontextfenster

Eine typische Reaktion auf Fehler von Agenten ist, dem Modell mehr Kontext zu geben.

Mehr Dokumentation.

Mehr Gesprächsverlauf.

Mehr Dateien.

Mehr Tool-Output.

Irgendwann erhält der Agent alles und versteht weniger.

Kontext ist kein Speicher.

Er ist ein Aufmerksamkeitsbudget.

Anstatt bei jedem Durchlauf das gesamte Projekt hineinzuwerfen, gib dem Agenten eine kleine Karte, auf der steht, wo nützliche Informationen liegen.

1PROJEKTKARTE
2
3Produktregeln     -> docs/product/
4Architektur       -> docs/architecture.md
5Frontend          -> apps/web/
6Backend           -> services/api/
7Tests             -> tests/
8Befehle           -> docs/commands.md
9Sicherheit        -> docs/security.md

Dann erweitere nur, wenn es nötig ist.

1AUFGABE
2  |
3  v
4PROJEKTKARTE
5  |
6  v
7RELEVANTES SYSTEM
8  |
9  v
10EXAKTE DATEIEN
11  |
12  v
13LOKALE ANWEISUNGEN

Die Quelle beschreibt das als „progressive disclosure“ (schrittweise Offenlegung): Der Harness sollte mehr Informationen laden, weil die Aufgabe sie braucht – nicht einfach, weil diese Informationen existieren.

Das Ziel ist nicht maximaler Kontext.

Das Ziel ist maximales nützliches Signal.

4. Schalte ein Gateway zwischen Modell und Tools

Ein Modell mit zwanzig Tools ist nicht automatisch zwanzigmal leistungsfähiger.

Es hat vielleicht einfach zwanzig zusätzliche Möglichkeiten zu scheitern.

Jedes Tool sollte einen Vertrag haben.

1TOOL: edit_file
2
3INPUTS
4Pfad
5Patch
6
7VORAUSSETZUNGEN
8Pfad existiert
9Pfad liegt innerhalb des Workspace
10
11ERFOLG
12Patch angewendet
13Diff zurückgegeben
14
15FEHLER
16strukturierter Fehler
17kein teilweises Überschreiben
18
19RISIKO
20umkehrbar

Dann sieht der Ausführungspfad so aus:

1MODELL SCHLÄGT VOR
2      |
3      v
4GATEWAY PRÜFT
5      |
6      v
7RICHTLINIE AUTORISIERT
8      |
9      v
10TOOL FÜHRT AUS
11      |
12      v
13HARNESS PROTOKOLLIERT ERGEBNIS

Das Modell entscheidet, welche Aktion es durchführen möchte.

Der Harness entscheidet, ob diese Aktion gültig, erlaubt und sicher ist.

Dieser Unterschied wird kritisch, sobald Tools Nachrichten senden, die Produktion verändern, Geld ausgeben oder Daten löschen können.

Ein gutes Tool-Gateway kann zudem Timeouts hinzufügen, Argumente validieren, Dateipfade einschränken, Fehler normalisieren und Retrys absichern.

Gute Tools reduzieren die Anzahl der Dinge, die das Modell erraten muss.

5. Verlagere das Gedächtnis aus der Konversation heraus

Die Konversation sollte nicht das führende System sein.

Lang laufende Agenten stoßen irgendwann an Kontextgrenzen, stürzen ab, starten neu oder übergeben die Arbeit an eine andere Session.

Wenn jede wichtige Entscheidung nur im Chatverlauf existiert, ist der Workflow extrem fragil.

Speichere dauerhafte Zustände separat.

1{
2  "task_id": "feature_042",
3  "status": "verifying",
4  "current_step": "mobile_check",
5
6  "completed": [
7    "implementation",
8    "unit_tests",
9    "desktop_check"
10  ],
11
12  "decisions": [
13    "bestehenden Export-Endpunkt wiederverwenden",
14    "aktuelles Datumsformat beibehalten"
15  ],
16
17  "artifacts": [
18    "export.csv",
19    "desktop-after.png"
20  ],
21
22  "open_risks": [
23    "Mobile Toolbar könnte überlaufen"
24  ],
25
26  "next_action": "Mobile Viewport rendern"
27}

Ein sinnvolles System unterteilt das Gedächtnis in vier Kategorien:

1FAKTEN
2stabiles Wissen
3
4ENTSCHEIDUNGEN
5was gewählt wurde und warum
6
7ZUSTAND
8wo der aktuelle Durchlauf steht
9
10LEKTIONEN
11Fehler, die künftige Durchläufe beeinflussen sollten

Die nächste Agenten-Session sollte den Arbeitszustand erben – keine komprimierte Zusammenfassung der vorherigen Konversation.

6. Mach Nachweise zum Tor zum Abschluss

Dass ein Agent „fertig“ sagt, ist kein Beweis dafür, dass die Arbeit erledigt ist.

Es ist nur ein weiterer Output des Modells.

Der Harness braucht beobachtbare Nachweise.

1BEHAUPTUNG                NACHWEIS
2
3„Bug ist behoben“         fehlschlagender Test läuft jetzt durch
4
5„Seite funktioniert“      Browser-Ablauf abgeschlossen
6
7„Daten sind korrekt“      Werte stimmen mit Quelle überein
8
9„Migration ist sicher“    Dry Run + Rollback erfolgreich
10
11„Aufgabe ist erledigt“    alle Akzeptanzprüfungen bestanden

Nutze zuerst deterministische Prüfungen.

1Syntax
2  |
3  v
4Typen
5  |
6  v
7gezielte Tests
8  |
9  v
10Integrationstests
11  |
12  v
13visuelle / semantische Prüfung
14  |
15  v
16menschliche Freigabe

Bitte kein weiteres Modell, etwas zu beantworten, das ein Compiler, ein Test, ein Schema oder eine Datenbankabfrage beweisen kann.

Nutze Modelle für Urteile.

Nutze deterministische Systeme für Fakten.

Das Modell erstellt das Artefakt.

Die Umgebung erzeugt Nachweise über das Artefakt.

Der Harness entscheidet, ob die Nachweise ausreichen.

7. Trenne den Erbauer vom Prüfer

Selbstkontrolle hat noch ein weiteres Problem.

Der Agent, der den Fehler gemacht hat, bringt oft genau dieselben Annahmen in die Überprüfung mit.

Eine robustere Architektur trennt den Arbeiter vom Prüfer.

1ERBAUER
2   |
3   v
4erstellt Kandidat
5   |
6   v
7PRÜFER
8   |
9   +-- prüft Vertrag
10   +-- sucht nach fehlenden Fällen
11   +-- testet unbelegte Behauptungen
12   +-- versucht, das Ergebnis zu brechen
13   |
14   +------ BESTANDEN ------> AKZEPTIEREN
15   |
16   +------ FEHLGESCHLAGEN --> NACHWEIS ZURÜCKGEBEN

Der Prüfer sollte nicht fragen:

Sieht das gut aus?

Er sollte fragen:

Was würde dies inakzeptabel machen?

Das verwandelt die Überprüfung von einer Bestätigung in einen Widerlegungsversuch.

Die Quelle empfiehlt ausdrücklich, der Verifizierung eigene Ablehnungskriterien und genug Unabhängigkeit zu geben, um die Annahmen infrage zu stellen, die zum ersten Ergebnis geführt haben.

8. Verlagere Berechtigungen aus dem Modell heraus

Manche Regeln sollten niemals davon abhängen, dass das Modell sich an sie erinnert.

1niemals ohne Freigabe veröffentlichen
2niemals Secrets offenlegen
3niemals das Ausgabenlimit überschreiten
4niemals außerhalb des Workspace schreiben
5niemals behaupten, Tests seien bestanden, wenn sie nicht liefen

Das sind keine Vorschläge für den Prompt.

Das sind Richtlinien.

Eine einfache Berechtigungsleiter:

1NIEDRIGES RISIKO
2
3lesen
4suchen
5prüfen
6
7-> automatisch
8
9UMKEHRBAR
10
11Workspace bearbeiten
12Tests ausführen
13Entwurf erstellen
14
15-> automatisch + Trace
16
17EXTERNE WIRKUNG
18
19senden
20deployen
21kaufen
22
23-> Freigabe erforderlich
24
25IRREVERSIBEL / SENSIBEL
26
27Daten löschen
28Credentials rotieren
29global veröffentlichen
30
31-> harte Sperre oder verboten

Je schwerer die Konsequenz, desto strenger die Kontrolle.

Das Modell darf die Aktion empfehlen.

Der Harness autorisiert sie.

Das Tool führt sie aus.

Autonomie bedeutet nicht das Fehlen von Kontrolle.

Sie ist Freiheit innerhalb eines durchgesetzten Rahmens.

9. Hör auf, blind zu wiederholen

Eine der schlechtesten Strategien zur Fehlerbehebung lautet:

Etwas ist fehlgeschlagen. Versuch es nochmal.

Wenn sich nichts ändert, bezahlt das System lediglich dafür, denselben Fehler zu reproduzieren.

Fehler sollten zuerst klassifiziert werden.

1TOOL-TIMEOUT
2-> Retry mit Backoff
3
4UNGÜLTIGE ARGUMENTE
5-> Tool-Aufruf reparieren
6
7FEHLENDER KONTEXT
8-> fehlende Quelle abrufen
9
10FEHLGESCHLAGENER TEST
11-> fehlerhaftes Verhalten untersuchen
12
13BERECHTIGUNG VERWEIGERT
14-> Freigabe anfordern
15
16WIDERSPRÜCHLICHE ANFORDERUNGEN
17-> eskalieren
18
19UNVERÄNDERTER WIEDERHOLTER FEHLER
20-> stoppen

Eine sinnvolle Agenten-Schleife sieht so aus:

1BEOBACHTEN
2   |
3   v
4ENTSCHEIDEN
5   |
6   v
7HANDELN
8   |
9   v
10MESSEN
11   |
12   +---- AKZEPTIEREN
13   |
14   +---- REPARIEREN
15   |
16   +---- ESKALIEREN
17   |
18   +---- STOPPEN

Jede Schleife sollte Grenzen für Versuche, Zeit, Kosten und zerstörerische Reichweite haben.

Ein zuverlässiger Agent muss wissen, wie er weitermacht.

Er muss aber auch wissen, wann sich ein weiterer Versuch nicht mehr lohnt.

10. Mach aus wiederholten Anweisungen Infrastruktur

Angenommen, der Prompt enthält:

Lass immer den Formatter laufen.

Diese Regel ist stärker, wenn der Formatter automatisch ausgeführt wird.

Angenommen, die Anweisungen sagen:

UI-Code darf nicht direkt auf die Datenbank zugreifen.

Das ist als Architekturtest, der bei einem Verstoß fehlschlägt, viel wirkungsvoller.

Die Entwicklung sieht so aus:

1ERKLÄRUNG
2      |
3      v
4CHECKLISTE
5      |
6      v
7TEMPLATE
8      |
9      v
10AUTOMATISIERTE PRÜFUNG
11      |
12      v
13DURCHGESETZTE RICHTLINIE

Der Prompt sollte Urteilsvermögen erklären.

Der Harness sollte Invarianten erzwingen.

Jeder wiederkehrende Fehler sollte eine Stufe weiter auf dieser Leiter nach unten wandern.

Irgendwann muss das Modell sich die Lektion gar nicht mehr merken.

Die Umgebung merkt sie sich für das Modell.

11. Protokolliere den Durchlauf

Ein perfektes Endergebnis kann einen katastrophalen Ausführungsweg verbergen.

Vielleicht hat der Agent auf die falsche Quelle zugegriffen.

Vielleicht hat er einen fehlgeschlagenen Befehl ignoriert.

Vielleicht hat er eine externe Aktion doppelt ausgeführt.

Vielleicht hat er das Zehnfache des geplanten Budgets verbraucht.

Vielleicht hatte er aus dem falschen Grund recht.

Protokolliere genug Informationen, um rekonstruieren zu können, was passiert ist.

109:14  Aufgabenvertrag erstellt
209:15  architecture.md geladen
309:17  checkout.ts bearbeitet
409:18  gezielter Test fehlgeschlagen
509:21  Implementierung repariert
609:22  gezielter Test bestanden
709:24  Integrationstest bestanden
809:25  Deployment blockiert: Freigabe erforderlich

Nützliche Traces umfassen Kontextquellen, Tool-Aufrufe, Zustandsänderungen, Verifizierungsergebnisse, Gründe für Retrys, Freigabeentscheidungen, Kosten und Latenz.

Es geht nicht darum, zum Spaß Logs zu sammeln.

Es geht darum, Fehler lokal zu machen.

Wenn Schritt 18 scheitert, solltest du Schritt 18 reparieren können.

Du solltest nicht den gesamten Durchlauf neu abspielen müssen.

12. Gib jedem Durchlauf einen Beleg

Zwinge Menschen nicht, einen Chatverlauf mit vierzig Nachrichten zu prüfen.

Fasse das Ergebnis in einem kurzen Beleg zusammen.

1ZIEL
2
3Doppelte Anwendung von Gutscheinen beheben.
4
5GEÄNDERT
6
7Checkout-Validierung
8Regressionstest
9
10VERIFIZIERT
11
12Lint bestanden
13Unit-Tests bestanden
14Integrationstest bestanden
15
16NICHT VERIFIZIERT
17
18Zahlungsanbieter in Produktion
19
20RISIKEN
21
22Legacy-Mobile-Client nicht verfügbar
23
24FREIGABE ERFORDERLICH
25
26Deployment auf Staging

Das ist keine Zusammenfassung dessen, was laut Modell passiert ist.

Es ist eine Zusammenfassung dessen, was der Harness nachweisen kann.

Genau dieser Unterschied macht den Beleg wertvoll für Reviews, Übergaben und zukünftige Agenten-Sessions.

13. Lass jeden Fehler den Harness verbessern

Die meisten Teams reparieren das fehlerhafte Ergebnis.

Der bessere Ansatz ist, das System zu reparieren, das den Fehler zugelassen hat.

1FEHLENDER KONTEXT
2-> Projektkarte verbessern
3
4FALSCHES TOOL
5-> Routing oder Tool-Vertrag verbessern
6
7SCHLECHTES ERGEBNIS
8-> Validator hinzufügen
9
10ENDLOSE SCHLEIFE
11-> Retry-Limit hinzufügen
12
13UNSICHERE AKTION
14-> Berechtigungssperre hinzufügen
15
16VERLORENE ENTSCHEIDUNG
17-> Zustand persistieren
18
19UNBEKANNTER FEHLER
20-> Tracing verbessern

Hier beginnt Harness Engineering, sich zu verzinsen.

Ein repariertes Ergebnis hilft einem einzigen Durchlauf.

Ein reparierter Harness verbessert jeden darauffolgenden Durchlauf.

Die besten Agenten-Systeme werden zuverlässiger, weil Fehler Infrastruktur hinterlassen.

14. Starte mit dem kleinsten nützlichen Harness

Du brauchst zum Start keine riesige Orchestrierungsplattform.

Baue in Schichten auf.

1LEVEL 0
2
3Prompt
4Modell
5
6LEVEL 1
7
8Aufgabenvertrag
9Projektkarte
10Tools
11
12LEVEL 2
13
14strukturierter Zustand
15Verifizierung
16begrenzte Schleife
17
18LEVEL 3
19
20Berechtigungen
21Traces
22Wiederherstellung
23menschliche Sperren

Eine kurze Rechercheaufgabe braucht vielleicht nur einen Prompt und ein Review.

Eine sechsstündige Coding-Aufgabe mit Datei-, Netzwerk- und Deployment-Zugang braucht deutlich mehr.

Füge Komplexität erst hinzu, wenn die Fehleranfälligkeit es rechtfertigt.

Nicht, weil Agenten-Architektur cool aussieht.

Die Harness-Engineering-Checkliste

Bevor du einem Agenten echte Autonomie gibst, frage dich:

1[ ] Ist der Erfolg vor der Ausführung definiert?
2
3[ ] Kann der Agent den richtigen Kontext finden,
4    ohne alles laden zu müssen?
5
6[ ] Hat jedes Tool einen klaren Zweck,
7    ein Schema und einen Fehlerzustand?
8
9[ ] Werden wichtige Entscheidungen
10    außerhalb der Konversation gespeichert?
11
12[ ] Erfordert der Abschluss Nachweise?
13
14[ ] Sind riskante Aktionen durch Richtlinien geschützt?
15
16[ ] Hat jede Schleife ein Retry-Limit?
17
18[ ] Kann der Durchlauf nach einer Unterbrechung fortgesetzt werden?
19
20[ ] Kannst du jede wichtige Aktion rekonstruieren?
21
22[ ] Verbessert ein Fehler eine Regel, ein Tool,
23    einen Test, eine Karte oder eine Berechtigung?
24
25[ ] Kann die finale Änderung rückgängig gemacht werden?

Wenn mehrere Antworten „Nein“ lauten, wird ein stärkeres Modell den Agenten nicht automatisch zuverlässig machen.

Es macht den Fehler vielleicht nur schneller und teurer.

Der eigentliche Wandel

Prompt Engineering fragt:

Was soll ich dem Modell sagen?

Context Engineering fragt:

Was sollte das Modell genau jetzt wissen?

Harness Engineering fragt:

Welches System lässt das Modell handeln, seine Arbeit überprüfen, sich von Fehlern erholen und sicher arbeiten?

1PROMPT
2-> Anweisung
3
4KONTEXT
5-> Arbeitssicht
6
7HARNESS
8-> Betriebsumgebung
9
10SCHLEIFE
11-> lokale Korrektur
12
13GRAPH
14-> Koordination

Modelle werden sich weiter verändern.

Der dauerhafte Vorteil entsteht um sie herum.

Deine Verträge werden besser.

Deine Tools werden besser.

Deine Tests werden besser.

Dein Zustand wird sauberer.

Deine Berechtigungen werden sicherer.

Deine Wiederherstellungslogik wird intelligenter.

Deine Fehler werden zu Infrastruktur.

So werden leistungsfähige Modelle zu zuverlässigen Agenten.

Das ist Harness Engineering.

Wenn du bis hierhin gelesen hast

Speichere dir diesen Guide als Lesezeichen.

Folge mir auf X: x.com/0xjmori

Abonniere meinen Substack: substack.com/@lunarresearcher

Schick diesen Artikel jemandem, der immer noch versucht, jeden Agenten-Fehler mit einem längeren Prompt zu beheben.