Öffnest du die Motorhaube eines modernen Autos, um das Bremssystem zu verstehen, siehst du tausende Kabel, Schläuche und Steuergeräte – aber wo genau sitzt die Logik, die bei einer Vollbremsung die Räder blockiert? Genau so geht es Entwicklern, die den Quellcode eines KI-Agenten studieren. Sie sehen Tausende von Dateien, aber die entscheidende Frage „Fragt der Agent den Benutzer, bevor er eine Datei löscht?“ ist nicht auf einen Blick zu beantworten.
Das Problem ist nicht fehlender Code. Es ist die fehlende Verbindung zwischen was das System tut (seinem Verhalten) und wo dieses Verhalten im Code umgesetzt wird. Ein Forscherteam um Ruhan Wang von Tencent HY LLM Frontier entwickelte dafür das Harness Handbook. Es ist kein weiterer Code-Index, sondern eine navigierbare Verhaltenslandkarte. Sie ordnet den verstreuten Implementierungscode in logische Verhaltenseinheiten und verknüpft jeden Schritt mit überprüfbaren Codebelegen. So können Entwickler, Auditoren und andere KI-Agenten das System verstehen, überprüfen und anpassen – ohne sich durch 2000 Dateien quälen zu müssen.
Warum ein Agenten-Harness ein Handbuch auf Verhaltensebene braucht
Bei KI-Agenten denken wir oft zuerst an die Fähigkeiten des Modells. Sobald der Agent echte Arbeit erledigt, verschiebt sich die Frage: Nicht „Was kann das Modell?“, sondern „Was erlaubt das System dem Modell zu tun?“. Ob ein Befehl ausgeführt wird, ob der Benutzer um Erlaubnis gefragt wird oder ob ein Fehler abgefangen wird – das entscheidet nicht das Modell allein, sondern der sogenannte Harness, die ausführende Hülle um das Modell herum.
Ein solcher Harness ist nicht trivial. In einem Produktionssystem wie Codex – hier als Beispiel – koordiniert der Harness das Modell, die Werkzeuge, den Zustand, die Berechtigungen und die Ausführungsumgebung. Das Ergebnis: 2.267 Dateien, über 34.000 Funktionen und fast 160.000 Code-Verbindungen. Eine klassische Dateistruktur zeigt nur, wo Code liegt, nicht wie die Teile zusammenwirken, um ein bestimmtes Verhalten zu erzeugen. Suchst du nach „delete“ oder „confirm“, erhältst du Fragmente, die du mühsam zusammensetzen musst.
Besser: Starte beim Verhalten und folge den Spuren zurück zum Quellcode. Genau das bietet das Handbook. Es erfüllt drei Zwecke: Verstehen – wie der Harness einen Benutzerauftrag durchläuft. Auditieren – ob die Sicherheitsversprechen der Dokumentation tatsächlich im Code eingehalten werden. Anpassen – um einen eigenen Agenten auf Basis des bestehenden Harness zu bauen. Alle drei Zwecke beginnen mit einer konkreten Verhaltensfrage und enden im Code als Beleg.
Warum ist ein Verhalten an so vielen Stellen verstreut?
Die Regel „Frage den Benutzer, bevor du eine Datei löschst“ klingt einfach. Um sie im Code zu überprüfen, musst du eine Kette von Entscheidungen nachvollziehen: Fordert das Modell eine Bestätigung an? Kann der Werkzeugaufruf abgefangen werden? Wo wird die Benutzerantwort gespeichert? Unter welchen Bedingungen wird die Löschung endgültig ausgeführt? Jedes Glied dieser Kette kann das Ergebnis verändern.
Ein Verhalten wird nicht von einer einzigen Funktion entschieden. Es wird gemeinsam von Prompts, Tool-Wrappern, Berechtigungskonfiguration, Zustandsverwaltung, Sandbox-Ausführung und Fallback-Pfaden bestimmt. Es gibt keine Funktion confirmBeforeDelete(). Du musst Prompts, Wrapper, Berechtigungen und Zustand bis zur Sandbox-Ausführung und zu den Ausweichpfaden verfolgen, bevor du sagen kannst, ob die Anfrage ausgeführt, abgelehnt oder in einen anderen Fluss umgeleitet wird.
Die Forscher nennen diese Suche Behavior Localization. Die Vollständigkeit der Rekonstruktion bestimmt die Qualität der Erklärung, der Risikoanalyse und der Änderungsgrenzen. Das Harness Handbook verwandelt diese versteckten Verhaltensketten in eine Karte, die du Schicht für Schicht durchblättern und gegen den Quellcode prüfen kannst.
Harness Handbook: Eine navigierbare Verhaltenskarte
Da ein einzelnes Verhalten viele Implementierungsorte haben kann, kann das Handbook nicht einfach den Dateibaum neu verpacken. Stattdessen stellt es den Harness aus Verhaltensperspektive dar, mit drei Ebenen – L1, L2, L3 – die die Frage Schritt für Schritt eingrenzen. Jede Ebene bewahrt überprüfbare Codebelege, sodass du jede Erklärung nachvollziehen und spätere Änderungen im Quellcode verankern kannst.
L1 – Systemüberblick: Statt Dateien und Funktionen aufzulisten, folgt L1 einem Benutzerauftrag durch das gesamte System: Wie tritt der Auftrag ein, welche Stufen durchläuft er, wie bewegt sich der Zustand zwischen ihnen, und wie wird die Modellausgabe zu einer echten Aktion? Sie beantwortet zuerst: Wie läuft dieser Harness im Ganzen ab?
L2 – Verhaltenseinheiten-Überblick: Diese Ebene zerlegt den Systemablauf in Verhaltenseinheiten. Jede Einheit erfasst eine zusammenhängende Klasse von Verhalten und dokumentiert ihre Verantwortlichkeiten, Ein- und Ausgaben, Abhängigkeiten und Schlüsselzustände. Auf dieser Ebene siehst du, wie komplexes Verhalten zerlegt wird und wie die Teile im Gesamtablauf wieder zusammenhängen.
L3 – Verhaltenseinheit im Detail: Hier zoomst du in eine einzelne Einheit hinein: Wann ein Verhalten ausgelöst wird, wie es ausgeführt wird, wie sich der Zustand ändert, welcher Pfad nach einer Ausnahme oder einem Fehler genommen wird und welche Dateien und Funktionen den Beleg liefern. „Vor dem Löschen einer Datei bestätigen“ ist keine allgemeine Regel mehr, sondern eine überprüfbare Kette einzelner Entscheidungen.
Ein konkretes Beispiel aus der Arbeit der Forscher: Die L3-Einheit für „Bestätigung vor Dateilöschung“ listet auf, welcher Trigger (das Modell sendet delete_file(path)), welche Berechtigungsregel (Dateilöschung ist als risikoreich markiert), welche Zustandsänderung (Bestätigungsanfrage und Antwort werden aufgezeichnet), welcher Ausführungspfad (Benutzer genehmigt → Sandbox-Runner, Ablehnung → Abbruch) und welche Randfälle (Headless-Modus, Auto-Approval) relevant sind. Für jeden Schritt gibt es Code-Belege wie tools/file_ops.py:32-78.
Wie wird die Verhaltenskarte aus dem Code erzeugt?
Damit das Handbook vertrauenswürdig ist, darf
Quelle: ruhan-wang.github.io
