Eval Harness für KI-Agenten: reproduzierbare Evaluierungen

Idee in 30 Sekunden

Eval harness ist ein Weg, denselben Satz von Szenarien für einen Agenten auszuführen, Ergebnisse nach denselben Regeln zu bewerten und candidate mit baseline zu vergleichen.

Problem

Ohne eval harness testen Teams Agenten oft manuell:

• sie starten einige Anfragen im Chat;
• sie schauen auf ein paar Antwortbeispiele;
• sie schließen daraus, dass die Änderung sicher aussieht.

Das liefert kein stabiles Bild: Eine Änderung kann auf zufälligen Beispielen gut aussehen, aber wichtige Production-Szenarien brechen.

Häufigste Folgen:

• candidate und baseline lassen sich nicht fair vergleichen;
• Regressionen sind schwer reproduzierbar;
• CI hat keine klare Regel, wann ein Release blockiert werden muss.

Kernkonzept / Modell

Eval harness ist kein einzelner Test, sondern eine Prüfkette: fixiertes Dataset, kontrollierte Laufbedingungen, Bewertung, Vergleich mit baseline und Report.

Je stabiler diese Komponenten sind, desto kleiner ist die Chance, dass diff zwischen candidate und baseline durch Laufbedingungen statt durch echtes Verhaltensänderung entsteht.

Wie es funktioniert

In der Praxis läuft eval harness als Teil der release pipeline. Jede Änderung durchläuft denselben Satz von Szenarien.

Eval harness ersetzt Unit-Tests nicht. Unit-Tests prüfen lokale Komponenten, harness prüft Systemverhalten auf vollständigen Szenarien.

Umsetzung

In der Praxis basiert eval harness auf ein paar einfachen Regeln. Die Beispiele unten sind schematisch und nicht an ein bestimmtes Framework gebunden.

1. Struktur eines Testfalls (test case)

case = {
    "id": "price_btc_basic",
    "input": "What is the price of BTC?",
    "expected_tool": "crypto_price_api",
    "checks": ["tool_selection", "valid_output_schema"],
}

Klare Cases vereinfachen Regressionsanalyse und reduzieren Mehrdeutigkeit bei Laufanalyse.

2. Runner für Case-Ausführung

def run_case(agent, case):
    result = agent.run(case["input"])
    return {
        "case_id": case["id"],
        "selected_tool": result.selected_tool,
        "output": result.output,
        "stop_reason": result.stop_reason,
    }

Neue Version und baseline müssen unter denselben Bedingungen laufen: gleiche Timeouts, tool-mocks, Limits und Runtime-Konfiguration.

3. Bewertung und Vergleich mit baseline

def evaluate_case(run_result, case):
    checks = {
        "tool_selection": run_result["selected_tool"] == case["expected_tool"],
        "valid_output_schema": isinstance(run_result["output"], dict),
    }
    return {"passed": all(checks.values()), "checks": checks}

candidate = run_eval_suite(agent=candidate_agent, dataset=dataset)
baseline = load_baseline_report("reports/baseline.json")
diff = compare(candidate, baseline)

Für offene Aufgaben ergänzt man deterministische Checks meist um LLM-as-a-judge als separate Bewertungsschicht. Baseline sollte ebenfalls versioniert und an konkrete Modellversion, Prompt und Runtime-Konfiguration gebunden werden.

4. Report und CI gate

summary = build_summary(candidate, diff)

if summary["task_success_rate"] < 0.92:
    fail("gate_failed:task_success_rate")
if summary["hallucination_rate"] > 0.03:
    fail("gate_failed:hallucination_rate")

write_json("reports/eval-summary.json", summary)

Ein guter eval harness speichert immer Artefakte: Ergebnisse pro Case, Fail-Gründe, diff gegen baseline und den Gesamtbericht.

5. Release gate in der Gesamtstrategie

Kriterien für Release-Blockierung und Schwellenwerte des CI gate sind separat in Testing Strategy beschrieben, damit sie nicht in jedem Artikel dupliziert werden.

Typische Fehler

Instabiles Dataset

Szenarien werden laufend "on the fly" geändert, deshalb sind Ergebnisse zwischen Läufen nicht fair vergleichbar.

Typische Ursache: Dataset ist nicht versioniert und hat keine festen Case-IDs.

Nicht fixierte Modellversion

LLM-Provider aktualisieren Modelle manchmal ohne Änderung des generischen Namens. Wenn Version nicht fixiert ist (z. B. gpt-4o-2024-08-06), können Ergebnisse zwischen Läufen wechseln.

Typische Ursache: Modellalias (gpt-4o, sonnet) wird ohne version pinning verwendet.

In Production-Systemen wird meist eine konkrete Modellversion oder Snapshot-Version fixiert.

Manueller Lauf statt Automatisierung

Harness wird nur ausgeführt, wenn "Zeit da ist", nicht bei jeder relevanten Änderung.

Typische Ursache: keine CI-Integration und kein klares pass/fail gate.

Kein Vergleich mit baseline

Team schaut nur auf absolute candidate-Metriken und übersieht subtile Regressionen.

Typische Ursache: Report enthält keinen diff zwischen candidate und baseline.

Gemischte deterministische und nicht-deterministische Checks

Deterministische Checks und LLM-as-a-judge werden in einen "Gesamtscore" gemischt, daher ist unklar, was genau gebrochen ist.

Typische Ursache: keine separaten Bewertungssektionen für unterschiedliche Check-Typen.

Fehlende Lauf-Artefakte

Es gibt nur die finale Erfolgsquote ohne Traces und Checks pro Case.

Typische Ursache: harness speichert keine detaillierten Ergebnisse in Report-Dateien.

Instabile eval-Läufe

Derselbe Case besteht mal und fällt mal, daher vertraut niemand dem Report.

Typische Ursache: instabile externe Umgebung, fehlende mocks, schwankende Timeouts oder uneinheitliche Laufbedingungen.

Kurzfassung

FAQ

Q: Ist eval harness einfach ein Testsatz?
A: Nein. Es ist ein gesteuerter Prozess: dataset, runner, evaluators, Vergleich mit baseline und CI gate.

Q: Kann man auf LLM-as-a-judge verzichten?
A: Ja, wenn Aufgaben gut durch deterministische Checks abgedeckt sind. Für offene Aufgaben wird LLM-as-a-judge meist als separate Bewertungsschicht ergänzt.

Q: Wie oft sollte eval harness laufen?
A: Mindestens bei jeder Änderung, die Agentenverhalten beeinflussen kann: Modell, Prompts, Tools oder Runtime-Regeln.

Q: Was ist am wichtigsten in der ersten Harness-Version?
A: Stabiles Dataset, gespeicherte baseline, klare pass/fail-Schwellen und Lauf-Artefakte.

Was als Nächstes

Für das Gesamtbild startet mit Testing Strategy. Danach deckt kritische Logik über Unit Testing ab, baut ein stabiles Golden Datasets, und ergänzt für Versionsänderungen Regression Testing.

Wenn erste reale Incidents auftreten, ergänzt Replay and Debugging und nehmt diese Cases in das Dataset eures eval harness auf.