getedgehq/agent-evals

Agent Evals

Eine Eval beantwortet eine Frage: Hat der Agent den Job richtig gemacht? Alles hierunter ist eine Möglichkeit, diese Frage zuverlässiger, günstiger und häufiger zu stellen.

Basierend auf der Evals-Meisterklasse von Alex Lieberman mit Viv (LangChain), 2026: youtube.com/watch?v=zLeG-XJtbIE. Die Struktur (Einfach, Schwer, Gott-Modus) stammt von ihnen. Fehler in dieser Fähigkeit sind unsere.

Beginne damit, dem Benutzer drei Dinge zu fragen

1. Welchen echten Job erledigt der Agent? Nenne das System, das er berührt (CRM, Posteingang, Repository, Datenbank).
2. Wer im Unternehmen macht diesen Job heute am besten? Dessen Urteil ist die Grundwahrheit.
3. Läuft der Agent bereits in Produktion? Wenn ja, werden Traces irgendwo gespeichert?

Wähle den Modus basierend auf den Antworten. Springe nicht in den Gott-Modus, ohne Aufgaben und Prüfer zu haben.

Einfacher Modus: Aufgaben und Prüfer

Eine Aufgabe ist ein kleiner, überprüfbarer Teil des echten Jobs. Ein Prüfer sagt, ob diese Aufgabe richtig ausgeführt wurde.

1. Schreibe 10 bis 30 Aufgaben, die nachahmen, was echte Kollegen tun. Beispiele für einen Vertriebsagenten:
   • nach einem Anruf eine Notiz in einem CRM-Datensatz hinzufügen
   • einen Interessenten finden, der nicht in der offensichtlichen Tabelle steht
   • eine Antwort-E-Mail entwerfen, ohne sie zu senden
2. Schreibe für jede Aufgabe den Prüfer. Bevorzuge, in dieser Reihenfolge:
   • Zustandsprüfung (ein Skript): das Feld war vorher leer und enthält nachher den richtigen Wert; das Tag email_sent existiert.
   • Checkliste (ein Modell oder ein Mensch): für alles, das nicht direkt überprüfbar ist, zerlege „gut“ in Ja/Nein-Fragen. „Höchstens drei Absätze?“, „Verwendet die Marken-Tonregeln?“
3. Halte jedes Urteil binär. Modelle, die nach einer Bewertung von 1 bis 10 gefragt werden, clustern um 7 und weichen aus. Ja/Nein kann nicht ausweichen.
4. Hole die Checkliste von der besten Person für den Job, schriftlich. Führe den Agent aus, überprüfe eine Stichprobe von Hand. Wenn eine Ausgabe die Checkliste besteht, sich aber trotzdem falsch anfühlt, ist die Checkliste unvollständig. Füge die fehlende Frage hinzu.

Ausgabe des einfachen Modus: ein Ordner mit Aufgaben, jede mit einer Anweisung und einem Prüfer, und einer Erfolgsquote.

Schwerer Modus: Umgebungen

Eine Umgebung ist der Ort, an dem der Agent die Arbeit erledigt: seine Dateien, Werkzeuge, Daten und Berechtigungen. Evaluiere niemals gegen Produktionsdaten. Ein Agent, der die Eval nicht besteht, bearbeitet auch das echte CRM.

1. Baue eine Kopie, die für den Agenten real aussieht: gleiche Tabellen, gleiche Werkzeuge, gefälschte Datensätze. Verpacke sie so, dass sie bei jedem Lauf auf den gleichen Zustand zurückgesetzt wird (ein Container ist die übliche Wahl).
2. Eine Aufgabe = Anweisung + Umgebung + Prüfer. Speichere sie zusammen.
3. Verwende keinen eigenen Runner, wenn du es vermeiden kannst. Harbor (github.com/harbor-framework/harbor) hat gemeinsame Formate für Aufgaben, Umgebungen und Prüfer und viele veröffentlichte Aufgaben, die du anpassen kannst.
4. Teste die Umgebung selbst. Deine erste ist falsch. Führe mehrere verschiedene Agenten oder Modelle durch sie und suche nach seltsamen Mustern:
   • ein starkes Modell scheitert, wo ein schwaches besteht
   • ein Agent findet die Antwort an einer Stelle, wo sie nicht sein sollte (eine Platzhalterzeile, eine durchgesickerte Datei). Agenten werden jeden Abkürzungsweg nehmen, um zu bestehen. Entferne das Leck.
5. Tagge jede Aufgabe nach Familie (Codierung, Vertrieb, Code-Review). Wenn ein neues Modell veröffentlicht wird, führe nur die Familien aus, in denen es wahrscheinlich gut ist.
6. Wähle Modelle mit einer Tabelle, nicht mit einem Gefühl. Führe jeden Kandidaten auf denselben getaggten Aufgaben aus. Zeichne Erfolgsquote, Kosten und Geschwindigkeit nebeneinander auf. Dann entscheidet ein Mensch: Sind 5 Punkte Genauigkeit das Dreifache der Kosten für diese Familie wert? Benutzernahe Aufgaben rechtfertigen normalerweise das Top-Modell; interne oft nicht.

Ausgabe des schweren Modus: eine Eval-Suite, die du mit einem Befehl auf jedem beliebigen Modell erneut ausführen kannst, mit einer Ergebnistabelle pro Aufgabenfamilie.

Gott-Modus: Die Verbesserungsschleife

Die Schleife: Der Agent läuft, erzeugt Traces, Fehler werden zu neuen Aufgaben, der Agent wird repariert, wiederhole.

1. Aktiviere das Tracing. Ein Trace ist das Protokoll jeder Aktion: jeder Tool-Aufruf, jede Nachricht, jedes Ergebnis. Niemand kann vorhersagen, was ein Agent tun wird. Jeder kann beurteilen, was er getan hat.
2. Speichere Traces an einem Ort. Für einen einzelnen Entwickler reichen die eigenen Protokolle des Agenten auf der Festplatte. Für ein Team verwende ein Tracing-Produkt mit Berechtigungen.
3. Richte einen zweiten Agenten auf die Traces aus. Seine einzige Aufgabe ist es, Muster zu finden. Gib ihm eine kurze Beschreibung von gutem und schlechtem Verhalten. Frage ihn nach:
   • fehlgeschlagenen oder wiederholten Tool-Aufrufen
   • Anweisungen, die er ignoriert oder nur halb befolgt hat
   • einem wiederkehrenden falschen Pfad (immer die falsche Tabelle durchsuchen, eine Firma machen, wenn nach drei gefragt wurde)
4. Wandle jeden bestätigten Fehler in eine Aufgabe in der Eval-Suite um, damit er nie leise zurückkehren kann.
5. Repariere den Agenten, zuerst den günstigsten Hebel:
   • Geschirr: Prompt, Tool-Beschreibungen, Tool-Set, Modellauswahl
   • Feinabstimmung eines kleinen offenen Modells auf die enge Aufgabe, sobald die Suite beweist, dass es dem großen Modell entspricht
6. Behalte einen Menschen bei der Definition von „gut“. Agenten können Korrekturen vorschlagen und Aufgaben entwerfen. Ein Mensch entscheidet immer noch, welche Aufgaben für das Geschäft wichtig sind, und überprüft neue. Das aufzuschreiben ist der Teil mit der höchsten Hebelwirkung der Schleife.

Regeln

• Keine Eval ohne einen benannten echten Job. Allgemeine Benchmarks sagen dir nicht, ob dein Agent funktioniert.
• Nur binäre Prüfer. Teile jede Bewertung in Ja/Nein-Fragen auf.
• Lasse niemals zu, dass eine Eval Produktionsdaten berührt.
• Eine Suite, die alles besteht, ist eine kaputte Suite. Suche nach Undichtigkeiten.
• Gib Erfolgsquoten mit der Anzahl der Aufgaben daneben an („21 von 30“), niemals einen nackten Prozentsatz.