Dein Agent wird bei seinen Tests schummeln
Was ich beim Bau von Agentest gelernt habe, einem Open-Source-Test-Runner für KI-Agents.
Der Test, der aus dem falschen Grund grün war
Einer meiner Agent-Tests wurde grün, und das hätte er nicht dürfen. Das Szenario hat ein Tool aufgerufen, für das ich vergessen hatte, einen Mock anzulegen. Mein Test-Runner hat das Richtige getan und einen Fehler geworfen. Das Agent-Framework hat dann sein Richtiges getan: Es hat den Fehler abgefangen, ihn dem Modell als ganz normales Tool-Ergebnis übergeben und das Modell weitermachen lassen.
Das Modell hat sich entschuldigt, einen anderen Weg genommen und das Gespräch zu Ende geführt. Jede Assertion ab diesem Punkt hat ein Gespräch geprüft, das so nie wirklich stattgefunden hat. Der Report hat ein vages Folgesymptom gezeigt, nicht die eigentliche Ursache.
Dieser Bug fasst zusammen, was mir der Bau von Agentest beigebracht hat. Ein Agent ist darauf gebaut, sich von Fehlern zu erholen, und das gilt auch für Fehler in deinem Test-Setup. Deine Tests musst du mit genau dem im Kopf entwerfen.
Agent-Tests sind näher an UI-Tests als an API-Tests
Ein API-Test schickt einen Request und prüft die Response. Ein Agent bricht alle drei Annahmen, die dahinterstehen:
- Es ist ein Gespräch, kein Aufruf. Was der Agent in Runde vier tut, hängt davon ab, was der User in Runde zwei gesagt hat.
- Der Agent wählt die Tools. Welche Tools er aufruft, in welcher Reihenfolge und mit welchen Argumenten, ist genau das Verhalten, das du testen willst.
- „Richtig“ ist unscharf. Zwei gleich gute Antworten können kein einziges Wort gemeinsam haben.
Als ich mich umgesehen habe, waren Eval-Plattformen gut darin, Outputs im Nachhinein zu bewerten. Agent-Frameworks haben mir die Bausteine gegeben. Keins von beiden hat meinen Agent mit einem Befehl in der CI durch ein realistisches Gespräch laufen lassen. Ich wollte etwas, das wie Playwright funktioniert: eine Welt aufsetzen, den Agent darin handeln lassen und dann prüfen, was er getan hat.
Lektion 1: Dein Agent wird um dein Test-Harness herumarbeiten
Der Bug vom Anfang kam daher, dass ich einen geworfenen Fehler als verlässliches Signal behandelt habe. In einem normalen Test wandert ein Fehler aus einem Mock den Stack hinauf und lässt den Test fehlschlagen. In einem Agent-Test kommt er meistens nicht so weit.
Agent-Frameworks fangen Tool-Fehler absichtlich ab. LangGraphs ToolNode macht das standardmäßig, damit sich das Modell erholen kann, wenn ein echtes Tool ausfällt. Sie können „die Wetter-API hat ein Timeout“ nicht von „das Test-Harness hat für das hier keinen Mock“ unterscheiden. Beides kommt beim Modell als Tool-Ergebnis an, und das Modell tut, was es gut kann: Es arbeitet drumherum.
Die Lösung war, mich nicht mehr auf das Werfen zu verlassen. Der Mock-Resolver schreibt jetzt jeden Aufruf ohne Mock in ein Protokoll, bevor er wirft. Der Simulator prüft dieses Protokoll, nachdem der Agent fertig ist, egal was der Agent meldet:
// Record BEFORE throwing: the throw may be swallowed downstream.
this.unmocked.push({ toolName, turnIndex, message: error.message })
throw error
// ...after the conversation ends:
const unmocked = unmockedError(mockResolver)
if (unmocked) return { conversationId, turns, error: unmocked }
Daraus sind drei Regeln entstanden:
- Ein fehlender Mock ist die Grundursache. Wenn danach noch etwas anderes schiefgegangen ist, melde den fehlenden Mock statt des Symptoms.
- Schlag fehl, bevor du prüfst. Sonst besteht eine Assertion wie „dieses Tool darf nie aufgerufen werden“ trivial bei einem Gespräch, das vorzeitig abgebrochen ist.
- Nenn alle fehlenden Mocks auf einmal. Dasselbe Tool zweimal aufzurufen ist eine Lücke, nicht zwei. Liste jedes einzelne Tool auf, damit dir ein einziger Lauf alles sagt, was zu beheben ist.
Der allgemeine Punkt: Jeder Fehler, den dein Harness wirft, wird zum Input für das System, das du testest. Entwirf das Harness so, dass es das letzte Wort hat.
Lektion 2: Sei streng bei Mocks, mit einem ausdrücklichen Notausgang
Sobald Aufrufe ohne Mock jedes Mal fehlschlugen, ist sofort ein neues Problem aufgetaucht. Manche Aufrufe gehören gar nicht dem Agent. Die Integration löst sie selbst aus: Marker, die einem Szenario sagen, dass etwas passiert ist, auf die ein Szenario prüfen kann und die es meistens ignoriert. Mit strengem Mocking wurde jeder dieser Marker zu einem Mock, den jedes Szenario mitliefern musste.
Die verlockende Lösung ist ein globaler Schalter „Tools ohne Mock erlauben“. Der hätte den ursprünglichen Bug direkt zurückgebracht. Stattdessen kann der Aufrufer jetzt einen einzelnen Aufruf als optional markieren:
await ctx.resolveTool('progress_marker', args, { optional: true })
Ein optionaler Aufruf ohne Mock liefert undefined, wirft nicht und landet nicht im Protokoll. Alles andere bleibt streng. Die Regel, die ich weitergeben würde: Lockere die Strenge nicht global. Füge eine benannte Ausnahme genau an der Stelle des Aufrufs hinzu, an der der Aufrufer weiß, dass der Aufruf keine Rolle spielt.
Lektion 3: Du brauchst zwei Arten von Agent-Tests
Ein simulierter User, der von einem LLM gesteuert wird, ist gut darin, Fehler zu finden, an die du nicht gedacht hast. Er formuliert Dinge seltsam, überlegt es sich anders und gibt Informationen in der falschen Reihenfolge. Genau diese Vielfalt macht ihn zu einem schlechten Regressionstest, weil kein Lauf dasselbe Gespräch ist.
Am Ende hatte ich zwei Modi, und jeder deckt ab, was der andere nicht kann:
| Persona-basiert | Geskriptet über mehrere Runden | |
|---|---|---|
| Nachrichten des Users | Generiert aus einem Profil, einem Ziel und dem, was der User weiß | Vorab geschrieben |
| Gut für | Fehler finden, mit denen du nicht gerechnet hast | Regressionen erwischen |
| Determinismus | Niedrig, und das ist Absicht | Hoch |
| Assertions | Zielerreichung, Judge-Scores, Tool-Trajektorie | Die Tool-Trajektorie in jeder Runde |
Ein Persona-Szenario sieht so aus:
scenario('user books a morning slot', {
profile: 'Busy professional who prefers mornings.',
goal: 'Book a haircut for next Tuesday morning.',
knowledge: [{ content: 'The salon is open Tuesday 08:00-18:00.' }],
mocks: { tools: { check_availability: () => ({ slots: ['09:00', '10:30'] }) } },
})
Wenn ein Persona-Lauf einen Bug findet, mach daraus einen geskripteten Test, damit er nicht still zurückkommen kann.
Lektion 4: Prüf die Form der Trajektorie, nicht die genaue Abfolge
Meine ersten Trajektorie-Assertions haben eine exakte Liste von Tool-Aufrufen verlangt. Sie sind jedes Mal gebrochen, wenn der Agent die Verfügbarkeit zweimal geprüft oder etwas in einer leicht anderen Reihenfolge nachgeschlagen hat. Nichts davon war ein Bug.
Die genaue Reihenfolge ist fast nie die eigentliche Anforderung. Also wurden aus den Assertions Match-Modi, vom strengsten zum lockersten:
| Modus | Besteht, wenn | Verwende ihn für |
|---|---|---|
strict | Die Aufrufe exakt übereinstimmen, in der Reihenfolge | Protokolle, bei denen die Reihenfolge der Vertrag ist |
unordered | Dieselbe Menge an Aufrufen vorkommt, in beliebiger Reihenfolge | Unabhängige Abfragen |
contains | Die erwarteten Aufrufe in der Reihenfolge vorkommen, mit anderen Aufrufen dazwischen erlaubt | Die meisten echten Abläufe |
within | Jeder Aufruf aus einer erlaubten Menge kommt | Den Agent innerhalb einer Grenze halten |
Argumente werden genauso behandelt: Prüf die Felder, auf die es ankommt, und ignorier den Rest. Den lockersten Modus zu wählen, der noch etwas Sinnvolles prüft, ist eine Fähigkeit für sich. Zu locker, und der Test beweist nichts. Zu streng, und die Leute gewöhnen sich an, ihn zu ignorieren, wenn er fehlschlägt.
Lektion 5: Die schwierigen Teile sind nicht die, die du erwarten würdest
Das Gespräch zu beenden ist ein echtes Problem. Ein simulierter User muss entscheiden, wann sein Ziel erreicht ist. Sich selbst überlassen, dreht er sich entweder endlos im Kreis oder verabschiedet sich höflich zu früh. Funktioniert hat ein strukturiertes shouldStop-Feld in seiner Antwort, ein Stop-Token als Fallback, wenn das Modell das Schema ignoriert, und eine harte Obergrenze an Runden hinter beidem.
Fehler gruppieren, nicht nur zählen. Ein fehlgeschlagener Lauf kann 40 Runden als schlecht markieren, wenn es in Wirklichkeit nur drei Grundursachen gibt. Ein zusätzlicher LLM-Durchgang, der Fehler nach Ursache gruppiert, hat die Reports lesbar gemacht. Das Gruppieren zählt mehr als jede einzelne Metrik.
Rate Limits sind Teil des Produkts. Jedes Szenario verbraucht Tokens für den simulierten User, den Agent und mehrere Judges. Wegen der Rate Limits der Anbieter waren Retries mit Backoff unverzichtbar, dazu eine konfigurierbare Pause zwischen Szenarien. Dass lokale LLMs unterstützt werden, hat die innere Entwicklungsschleife kostenlos gehalten.
Eine npm-CLI auszuliefern ist immer noch mühsam. Der ESM-Build, der Shebang, die Modulauflösung und das Finden der tsconfig haben ungefähr acht Commits gebraucht, bis sie gepasst haben. Nichts davon war interessant, und alles davon hat User blockiert.
Was noch ungelöst ist
- Kannst du dem Judge trauen? LLM-as-Judge-Scores sind nützliche Signale, aber sie driften zwischen Modellversionen. Agentest entscheidet über Bestehen oder Fehlschlagen anhand von Schwellenwerten statt exakter Scores, aber ein Mensch muss die Fehlschläge trotzdem lesen.
- Die Kosten wachsen mit dem Ehrgeiz. Mehr Personas, mehr Runden und mehr Metriken vervielfachen die Token-Rechnung. Was bei jedem Commit läuft und was nächtlich, bleibt eine Ermessensfrage.
- Flakiness lässt sich eindämmen, nicht beseitigen. Persona-Läufe werden immer variieren. Das Ziel ist, diese Variation nützlich zu machen, damit sie neue Fehler aufdeckt statt Rauschen.
Probier es aus
Agentest ist Open Source unter der MIT-Lizenz. Installier es mit npm install @agentesting/agentest --save-dev und starte es mit npx agentest run. Es funktioniert mit jedem Agent hinter einem OpenAI-kompatiblen Endpoint oder einer einfachen TypeScript-Funktion.
- Code: github.com/r-prem/agentest
- Doku: r-prem.github.io/agentest
Wenn deine eigenen Agent-Tests schon einmal aus dem falschen Grund grün waren, würde mich interessieren, wie du draufgekommen bist.