Agent Harness von Grund auf: Sechs Phasen und ein Experiment, das die erzielten Fortschritte isoliert
Ein Harness kann die Benchmark-Ergebnisse stärker verbessern als das Modell selbst. Entwickeln Sie einen kleinen Agent-Harness in sechs Schritten und testen Sie jeweils nur eine Änderung, um herauszufinden, was tatsächlich hilft.
Quellen: Build an Agent Harness, Then Prove Which Change Moved the Score
Nehmen wir ein Grenzmodell sowie zwei Bewertungsumgebungen. Mit der ersten erreichte es bei einem Schlüsselbegriff-Test 62,7 Prozent, mit der zweiten 99,9 Prozent – und das alles in derselben Woche. Dieser Unterschied von 37,2 Punkten übertraf die 32,5 Punkte, die zwischen den beiden besten Ergebnissen in der Rangliste lagen. Somit kann die um das Modell herum konstruierte Infrastruktur, die vom Modell selbst unterschieden ist, die Ergebnisse stärker verändern als das Modell selbst. Im Folgenden finden Sie eine Übersicht dessen, was diese Infrastruktur beinhaltet, eine schrittweise Aufbauanleitung in sechs Etappen sowie den letzten Schritt, der zeigt, welche Ihrer Änderungen tatsächlich zu einer Verbesserung der Punktzahl führten.
Was befindet sich in einer Bewertungsumgebung?
Eine Bewertungsumgebung setzt sich aus sechs Komponenten zusammen, wobei keine davon die Modellgewichte berührt.
- Der Systemprompt – das sind die Anweisungen, die dem Modell vor der Aufgabe bezüglich seiner Rolle und Grenzen gegeben werden.
- Tool-Zugriff: Kann das Modell Code ausführen, Dateien lesen oder eine API aufrufen – und was erhält es dabei zurück?
Jedes dieser Elemente ist eine Entscheidung, die von jemandem getroffen wurde. Wenn man ein Framework verwendet, übernimmt man dessen Entscheidungen, ohne sie zu sehen. Das funktioniert gut, solange man nicht erklären muss, warum seine Ergebnisse von denen anderer abweichen.
Warum das wichtig ist
In der täglichen Arbeit zeigt sich dieser Effekt in geringerem Maße. Stellen Sie sich zwei Modelle vor, die bei einem Programmier-Benchmark 0,7 Punkte voneinander entfernt sind – dabei führt ein Wechsel der Verarbeitungsmethode zu einer Schwankung von etwa 5 Punkten. Der Unterschied, den Sie hier erkennen sollen, entspricht somit etwa einem Siebtel des Rauschens in der Messung. Ein öffentliches Beispiel bestätigt dies: Der interaktive Benchmark-Wert eines Modells soll sich verdreifacht haben, nachdem sein Anbieter zwei Einstellungen aktiviert hatte, die es ihm ermöglichten, seine Überlegungen von Schritt zu Schritt beizubehalten. Dasselbe Modell, nur mit der Möglichkeit, seine eigene Arbeitsweise beizubehalten.
Am aussagekräftigsten ist eine Anekdote aus der Praxis. Ein Ingenieur soll eine Programmieraufgabe fünfmal am selben Modell ausgeführt haben, wobei er jedes Mal ein einzelnes Komponentenstück hinzufügte. Ein leeres Repository ergab eine Erfolgsrate von etwa 20 Prozent. Ein Anleitungsfile erhöhte diese auf rund 60 Prozent, Verifizierungsanweisungen auf 80 Prozent und ein Fortschrittsfile auf fast 100 Prozent. Niemand hat diese Zahlen bestätigt, daher sollten sie nur als Veranschaulichung betrachtet werden. Entscheidend ist die Struktur, denn sie ermöglicht es, den Beitrag jeder einzelnen Ergänzung zu unterscheiden – etwas, was ein Vergleich zweier vollständiger Komplettsets nicht leisten kann.
Veröffentlichte Arbeiten deuten in dieselbe Richtung. Eine Technik entwickelt Anweisungen durch Reflexion über frühere Ausführungen und soll im Durchschnitt um 10 Prozent sowie bis zu 20 Prozent eine bessere Leistung als ein Basismodell des Verstärkungslernens erzielen, wobei die Anzahl der Ausführungen um bis zu 35 Mal geringer ist. Eine andere Technik betrachtet den angesammelten Kontext als ein sich entwickelndes Handbuch und verspricht eine Verbesserung um 10,6 Prozent bei Aufgaben für KI-Agenten. Ein dauerhaftes Notizbuch brachte ein Modell bei einer Rätselaufgabe von 10 Prozent auf 99 Prozent. Bei allen drei Methoden blieben die Gewichte unverändert.
Eine Erkenntnis spricht in die entgegengesetzte Richtung. Ein 2026 veröffentlichter Artikel teilte den „Harness“ in vier Teile auf, von denen jeder für sich evolvieren konnte, und erwartete, dass diese Struktur Vorteile bringt. Die Ergebnisse lagen bei 0,657 im Vergleich zu 0,642 für die Evolution einer einzigen flachen Zeichenkette – ein Unterschied, den die Autoren als unbedeutend bezeichnen. Ihrer Ansicht nach führt ein fester Optimierungsrahmen, der auf vier Teile verteilt ist, dazu, dass jeder Teil weniger Signale erhält. Zusätzliche Strukturen helfen standardmäßig nicht, und dieses negative Ergebnis ist wertvoller als die positiven, da es eine Interpretation ohne Anstrengung ausschließt.
Aufbau in sechs Schritten
Insgesamt umfasst das Ganze etwa hundert Zeilen ohne jegliches Framework. Man liefert eine einzige Funktion, die Text an ein Modell sendet und wieder Text zurückgibt.
Die erste Stufe ist das kleinste ausführbare Element: Man nimmt eine Aufgabe, ruft das Modell mit der entsprechenden Anweisung auf und misst die Dauer dieser Aufrufung.
import time
def run_task(task, call_model):
t0 = time.time()
output = call_model(task["prompt"])
return {"id": task["id"], "output": output,
"seconds": round(time.time() - t0, 2)}
In der zweiten Phase kann das Modell handeln und sehen. Ein Hilfsprogramm führt einen Shell-Befehl in einem Arbeitsverzeichnis mit Zeitlimit aus.
import subprocess
def run_command(cmd, workdir, timeout=60):
try:
r = subprocess.run(cmd, shell=True, cwd=workdir, timeout=timeout,
capture_output=True, text=True)
return {"exit": r.returncode, "stdout": r.stdout[-4000:],
"stderr": r.stderr[-4000:]}
except subprocess.TimeoutExpired:
return {"exit": None, "stdout": "", "stderr": "timed out"}
Zwei Entscheidungen sind bereits darin enthalten. Die Ausgabe wird auf die letzten 4.000 Zeichen gekürzt und die Befehle enden nach 60 Sekunden. Beide verändern das, was das Modell sieht, weshalb sie beide in Ihren Notizen als Teil des „Harness“ und nicht der Aufgabe aufgeführt werden sollten.
In der dritten Phase wird entschieden, was zwischen den Turns übertragen wird, indem die Nachrichtenliste aus dem Systemprompt, der Aufgabe und der Historie erstellt wird.
def build_messages(task, history, carry_reasoning=True):
msgs = [{"role": "system", "content": SYSTEM},
{"role": "user", "content": task["prompt"]}]
for turn in history:
if carry_reasoning:
msgs.append({"role": "assistant", "content": turn["output"]})
msgs.append({"role": "user", "content": format_result(turn["result"])})
return msgs
Machen Sie das Tragen von Argumenten zu einer Option statt zu einer fest codierten Wahl, denn Sie möchten beide Einstellungen messen.
In der vierten Phase wird eine Aktion aus dem Ausgabeergebnis des Modells extrahiert, ohne dass es stillschweigend fehlschlägt.
import re
ACTION = re.compile(r"<action>(.*?)</action>", re.S)
def parse_action(output):
m = ACTION.search(output)
if m:
return m.group(1).strip(), "matched"
fence = chr(96) * 3
alt = re.search(fence + r"(?:bash|sh)?\n(.*?)" + fence, output, re.S)
if alt:
return alt.group(1).strip(), "fallback_fenced"
return None, "no_match"
Protokollieren Sie den zweiten Rückgabewert, da er die meisten Informationen enthält. Wenn ein erheblicher Anteil der Ausführungen mit dem Fallback endet, misst der Parser eher die Formatierung als die Fähigkeit des Modells, und die Bewertung kann nicht unterscheiden, was vorliegt. Ein dazu passendes Beispiel: Ein Detektor, der prüft, ob ein Modell angibt, fertig zu sein, bestand fünf Validierungsfallen, überseh jedoch zwei offensichtliche Angaben, weil ein Punkt in einem Dateinamen ein satzbasiertes Muster unterbrach. Die Transkripte gaben an, dass die Tests bestanden, während der Detektor keinerlei Angaben feststellte.
Die fünfte Phase ist der Loop, wobei die Anzahl der Umdrehungen auf acht begrenzt ist.
MAX_TURNS = 8
def agent_loop(task, call_model, carry_reasoning=True):
history, workdir = [], task["dir"]
for turn in range(MAX_TURNS):
out = call_model(build_messages(task, history, carry_reasoning))
action, parse_status = parse_action(out)
result = run_command(action, workdir) if action else {"note": "no action"}
history.append({"output": out, "result": result, "parse": parse_status})
if action and task["done"](workdir):
return {"solved": True, "turns": turn + 1, "history": history}
return {"solved": False, "turns": MAX_TURNS, "history": history}
Hier ist task[„done“] eine von Ihnen bereitgestellte Funktion, die die Welt untersucht anstelle darauf zu vertrauen, was das Modell behauptet. Genau diese Unterscheidung verwandelt eine Demonstration in eine Messung.
Die sechste Stufe ist es, die das Ganze zu einem Instrument macht: eine Experimentfunktion, die jede Aufgabe unter jeder Variante ausführt und jede davon mehrmals wiederholt.
def experiment(tasks, call_model, variants, runs_per=2):
results = []
for name, config in variants.items():
for task in tasks:
for r in range(runs_per):
out = agent_loop(task, call_model, **config)
results.append({"variant": name, "task": task["id"], "run": r,
"solved": out["solved"], "turns": out["turns"],
"fallbacks": sum(1 for h in out["history"]
if h["parse"] != "matched")})
return results
variants = {"carry_on": {"carry_reasoning": True},
"carry_off": {"carry_reasoning": False}}
Ändern Sie eine Eigenschaft, halten Sie den Rest konstant, führen Sie beide Varianten aus und vergleichen Sie sie. Diese Methode fehlt in fast allen veröffentlichten Vergleichen. Ändern Sie gleichzeitig das Modell, die Eingabeanweisung und die Anzahl der Schritte – dann erfahren Sie nichts darüber, welche Änderung den Ergebniswert beeinflusst hat.
Was man messen sollte und was man erwarten kann
Vier Werte sind es wert, im Auge zu behalten. Erstens die Lösegeschwindigkeit für jede Variante. Zweitens die Anzahl der Schritte bis zur Lösung, denn eine Variante, die mit weniger Schritten zum gleichen Ergebnis kommt, ist kostengünstiger. Drittens, wie oft beim Parsen auf eine Rückfalllösung zurückgegriffen werden muss. Viertens, wie stark sich wiederholte Ausführungen derselben Aufgabe voneinander unterscheiden – das ist am aussagekräftigsten. Wenn identische Ausführungen unterschiedliche Ergebnisse liefern, könnte der Störfaktor größer sein als der gewünschte Effekt.
Sie sollten nicht überrascht sein, wenn das erste Ergebnis zeigt, dass die beiden Varianten gleichauf liegen. In einem Versuch mit dieser Konfiguration bearbeiteten zwei Grenzmodelle jeweils zehn kleine Fehlerbehebungsaufgaben zweimal, und alle Durchläufe waren erfolgreich – daher unterschied sich nichts zwischen den Modellen. Die Aufgaben waren zu einfach, um einen Unterschied festzustellen. Das ist das übliche Ergebnis und sagt etwas über die Aufgabensammlung aus, nicht über die Modelle. Wählen Sie Aufgaben, bei denen die Lösungsrate im mittleren Bereich liegt, deutlich unter dem Höchstwert.
Beschränkungen
Ein „Harness“ kann einem Modell keine Fähigkeiten verleihen, die ihm an Gewichten fehlen; daher ist jeder Vorteil auf das begrenzt, was die vorhandenen Gewichte zulassen. Ein „Harness“, der auf Ihre Aufgaben abgestimmt ist, wird ebenfalls nicht weiterhelfen. Was beim Beheben von Code erfolgreich ist, ist nicht unbedingt das, was bei offenen Erkundungen erfolgreich ist – schließlich unterscheiden sich die Fehlermuster.
Daher ging es nie darum, dass das Modell unwichtig ist. Vergleiche behandeln die beiden Modelle so, als würde sich nur eines unterscheiden, obwohl sich beide tatsächlich unterscheiden – doch nur das eine wird berücksichtigt.