Agents evaluieren und debuggen: Traces, Evals und Failure Modes

Ein Kunde bittet Ihren Reisebüro-Bot, „den günstigsten Flug nach Boston nächsten Freitag zu buchen", und der Bot buchte selbstbewusst einen Flug nach Boston in Lincolnshire, Großbritannien. Der Kunde wollte Boston, Massachusetts. Die Antwort sieht in Ordnung aus, bis Sie sehen, was der Agent tatsächlich getan hat: er hat nie das Tool aufgerufen, das Flughafencodes auflöst, also hat er geraten.

Genau in dieser Lücke zwischen „sieht in Ordnung aus" und „was tatsächlich passiert ist" spielt sich das Debuggen von Agents ab. Sie können nicht reparieren, was Sie nicht sehen.

Was ein Trace ist

Ein Agent ist ein KI-System, das Aktionen ausführen kann, nicht nur chatten. ErErDas Verhältnis von Interaktionen (Likes, Kommentare, Shares) zur Reichweite eines Inhalts. Zeigt, wie stark die Zielgruppe reagiert, gemessen an der Zahl der Personen, die den Inhalt gesehen haben.Vollständige Definition ansehen → ruft Tools auf (Funktionen wie „Flüge suchen", „eine Datei lesen" oder „eine E-Mail senden"), liest die Ergebnisse und entscheidet, was als Nächstes zu tun ist.

Ein Trace ist das aufgezeichnete Schritt-für-Schritt-Log eines Durchlaufs: jeder Prompt, den das Modell gesehen hat, jedes aufgerufene Tool, die übergebenen Argumente, was zurückkam und die finale Antwort. Denken Sie an einen Flugschreiber für eine einzelne Agent-Aufgabe.

Ohne Trace ist Debuggen Raten. Mit Trace springt der Fehler meist ins Auge.

Hier ein vereinfachter Trace der Boston-Buchung, in einfacher Sprache:

RUN #4471  |  user: "book the cheapest flight to Boston next Friday"

Step 1  LLM thinks: "User wants a flight. I'll search."
Step 2  TOOL CALL: search_flights(city="Boston", date="2026-01-16")
Step 3  TOOL RESULT: 3 flights returned  [destination code: BZZ, UK]
Step 4  LLM thinks: "Cheapest is £48. Booking it."
Step 5  TOOL CALL: book_flight(flight_id="BZZ-2231")
Step 6  TOOL RESULT: {"status": "confirmed"}
Step 7  LLM final: "Booked! £48 to Boston next Friday."

Der Fehler liegt in Schritt 2. Der Agent hat einen einfachen Städtenamen übergeben und ihn nie disambiguiert. Es gibt keinen „resolve_airport"-Schritt. Das Modell ist nicht am Reasoning gescheitert; im Workflow fehlte ein Schritt.

Das ist der Sinn von Tracing: es zeigt Ihnen, *wo* etwas kaputtgegangen ist, damit Sie wissen, *was* zu reparieren ist.

Einen Trace lesen: worauf Sie achten

Wenn Sie den Trace eines fehlerhaften Durchlaufs öffnen, suchen Sie nach diesen Punkten:

• Falsches Tool oder kein Tool. Hat der Agent aus dem Gedächtnis geantwortet, obwohl er ein Tool hätte aufrufen sollen? (Eine klassische Ursache für erfundene „Fakten".)
• Falsche Argumente. Richtiges Tool, falsche Inputs. Etwa city="Boston" ohne Land.
• Ignorierte Ergebnisse. Das Tool hat die richtigen Daten geliefert, aber der nächste Schritt des Modells hat sie ignoriert.
• Loops. Der Agent ruft dasselbe Tool immer wieder auf, ohne Fortschritt zu machen.
• Zu früh gestoppt. Er hat eine finale Antwort gegeben, bevor die Aufgabe fertig war.

Die meisten Agent-Fehler sind einer dieser fünf. Sie müssen keinen Code lesen, um sie zu erkennen; Sie lesen den Trace wie eine Geschichte und finden den Satz, der keinen Sinn mehr macht.

Woher Traces kommen

Sie bauen keinen Trace-Viewer selbst. Moderne Agent-Frameworks erzeugen Traces automatisch, und Observability-Tools zeigen sie als klickbare Timelines an. Offene, kostenlose Optionen sind Langfuse und Arize Phoenix, die beide den OpenTelemetry-Standard unterstützen und damit anbieterübergreifend funktionieren.

Das Agent SDK jedes Anbieters (das OpenAI Agents SDK, das Claude Agent SDK, Googles ADK) bringt ebenfalls eingebautes Tracing mit. Das Konzept ist überall identisch; nur die Buttons unterscheiden sich. Für das genaue Setup siehe die Provider-Deep-Dive-Blöcke.

So sieht das Erzeugen eines Trace in anbieterneutralem Pseudocode aus. Beachten Sie, dass der Loop nur das ist: denken, Tool aufrufen, Ergebnis zurückspeisen, wiederholen.

trace = []

while not done:
    response = model.generate(messages, tools=my_tools)
    trace.append({"step": "llm", "output": response})

    if response.tool_call:
        result = run_tool(response.tool_call)
        trace.append({"step": "tool",
                      "name": response.tool_call.name,
                      "args": response.tool_call.args,
                      "result": result})
        messages.append(result)   # Ergebnis an das Modell zurückspeisen
    else:
        done = True

save(trace)   # jetzt können Sie diesen Durchlauf später inspizieren

Die trace.append-Zeilen sind der ganze Trick. Loggen Sie jeden Schritt, während er passiert, und Sie kkDie durchschnittliche Zahl neuer Nutzer, die jeder bestehende Nutzer über Empfehlungen generiert. Über 1,0 verstärkt sich das Wachstum selbst und wird exponentiell.Vollständige Definition ansehen →önnen jeden Durchlauf danach nachspielen.

Häufige Failure Modes (und was sie behebt)

Wenn Sie ein paar Dutzend Traces gelesen haben, wiederholen sich die Muster. Hier die wichtigsten und die üblichen Fixes.

Halluzinierte Tool-Nutzung

Der Agent sagt „Ich habe die Datenbank geprüft", aber der Trace zeigt keinen Tool-Aufruf. Fix: die Anweisung verschärfen („Du musst lookup_order aufrufen, bevor du eine Frage zu einer Bestellung beantwortest") und, wenn das Framework es erlaubt, einen Tool-Aufruf für diesen Schritt erzwingen.

Falsches Argumentformat

Das Tool erwartet ein Datum wie 2026-01-16, aber der Agent sendet „nächsten Freitag". Fix: das Argumentformat in der Tool-Beschreibung klar beschreiben und einen Validierungsschritt einbauen, der falschen Input zurückweist und das Modell zum erneuten Versuch auffordert.

Verlorengehen bei langen Aufgaben

Bei einer Aufgabe mit 15 Schritten hat der Agent bei Schritt 10 vergessen, was er eigentlich tun wollte. Fix: die Aufgabe in kleinere Teilaufgaben zerlegen oder jedem Schritt eine kurze „aktuelles Ziel"-Erinnerung mitgeben.

Zu viele Tool-Aufrufe

Der Agent ruft für eine Frage fünfmal die Websuche auf und verbrennt Zeit und Geld. Fix: ein Schrittlimit setzen und ihn anweisen, zusammenzufassen, was er schon weiß, bevor er erneut sucht.

Der Fix ist fast immer eines von drei Dingen: eine klarere Tool-Beschreibung, eine klarere Anweisung oder ein GuardrailGuardrailRegeln und Kontrollen, die ein KI-System in sicheren, rechtskonformen und markengerechten Grenzen halten und unerwünschte Ausgaben blockieren.Vollständige Definition ansehen → (ein Limit oder eine Validierungsprüfung). Ein größeres Modell brauchen Sie selten.

Evals: wissen, ob eine Änderung wirklich geholfen hat

Sie haben den Boston-Fehler gefunden. Sie haben einen „resolve_airport"-Schritt ergänzt. Hat es funktioniert? Und hat es etwas anderes kaputtgemacht?

Hier kommen Evals ins Spiel. Ein Eval (kurz für Evaluation) ist ein wiederholbarer Test Ihres Agents gegen eine Reihe von Beispiel-Inputs mit bekannten guten Ergebnissen. Es ist das Agent-Äquivalent zur Checkliste, die ein Pilot vor jedem Flug durchgeht.

Der Kern ist ein Eval Set: eine kleine Sammlung von Testfällen, die Sie jedes Mal laufen lassen, wenn Sie den Agent verändern. Jeder Fall hat einen Input und eine Methode, den Output zu prüfen.

Fangen Sie mit einer einfachen Tabelle oder Datei an. Zehn bis zwanzig Fälle sind für den Anfang reichlich.

case_id | input                                    | check
--------|------------------------------------------|----------------------------
1       | "cheapest flight to Boston next Friday"  | destination country == "US"
2       | "flight to Paris"                        | asks which Paris OR picks FR
3       | "cancel my last booking"                 | calls cancel_booking exactly once
4       | "book London to Boston"                  | resolves BOTH cities
5       | "what's the weather"                     | does NOT call book_flight

Beachten Sie, dass die Checks konkret sind. Manche sind exakt („destination country == US"), manche verhaltensbezogen („ruft book_flight nicht auf"). Fall 5 ist ein Negativtest: er stellt sicher, dass der Agent etwas Falsches *nicht* tut.

Wie Sie ein Eval Set laufen lassen

Der Loop ist einfach:

1. Alle Fälle gegen den aktuellen Agent laufen lassen. Pass/Fail festhalten.
2. Eine Änderung machen (den Flughafen-Schritt ergänzen).
3. Alle Fälle erneut laufen lassen.
4. Vergleichen. Ist Fall 1 von Fail auf Pass gewechselt? Ist ein Fall von Pass auf Fail gewechselt?

Die letzte Frage fängt Regressionen ab: ein Fix, der still etwas kaputtmacht, das vorher funktionierte. Ohne Eval Set würden Sie den Fix ausliefern und es von einem verärgerten Kunden erfahren.

Outputs prüfen, die Sie nicht exakt abgleichen können

Viele Agent-Outputs sind keine exakten Strings. „Klar, ich habe Ihre Buchung storniert" und „Fertig, Ihre Buchung ist storniert" sind beide korrekt. Dafür gibt es zwei verbreitete Ansätze:

• Verhalten prüfen, nicht Wörter. Prüfen Sie, dass der Trace cancel_booking einmal aufgerufen hat. Das ist zuverlässiger als die Formulierung zu prüfen.
• LLM-as-judge. Nutzen Sie einen zweiten Modellaufruf, um die Antwort gegen eine Rubrik zu bewerten („Hat die Antwort die Stornierung bestätigt? ja/nein"). Nützlich, aber behandeln Sie die Scores als rauschbehaftet, nicht als Evangelium. Machen Sie Stichproben.

Bevorzugen Sie verhaltensbezogene Checks, wo es geht. Sie sind günstiger und weit stabiler als Text zu bewerten.

Alles zusammen: der Debug-Loop

Hier der ganze Workflow in der Reihenfolge. Das ist die Gewohnheit, die Sie aufbauen sollten.

1. Ein Durchlauf scheitert. Ein Nutzer meldet eine schlechte Antwort, oder ein Eval-Fall fällt durch.
2. Trace öffnen. Lesen Sie ihn wie eine Geschichte. Finden Sie den Schritt, der keinen Sinn mehr macht.
3. Den Failure Mode benennen. Falsches Tool? Falsche Argumente? Ignoriertes Ergebnis? Loop?
4. Eine Änderung machen. Klarere Anweisung, klarere Tool-Beschreibung oder ein Guardrail.
5. Eval Set laufen lassen. Bestätigen, dass der Zielfall besteht und nichts anderes regrediert ist.
6. Den fehlgeschlagenen Fall ins Eval Set aufnehmen, damit er nie wieder still regrediert.

Schritt 6 ist der, den Leute überspringen, und er ist der wertvollste. Jeder Fehler, den Sie beheben, wird zu einem permanenten Test. Über einige Monate wächst Ihr Eval Set zu einem echten Sicherheitsnetz, vollständig aus realen Fehlern gebaut.

Eine Änderung auf einmal ist ebenfalls wichtig. Wenn Sie den Flughafen-Schritt reparieren *und* die Anweisungen neu schreiben *und* das Modell tauschen, alles gleichzeitig, und der Score sich bewegt, wissen Sie nicht, welche Änderung es war. Eine Sache ändern, Evals laufen lassen, wiederholen.

Wichtigste Erkenntnisse

• Ein Trace ist Ihr Flugschreiber. Wenn ein Agent scheitert, öffnen Sie den Trace, bevor Sie irgendetwas anfassen. Der Fehler ist meist ein sichtbarer Schritt: ein fehlender Tool-Aufruf, ein falsches Argument oder ein ignoriertes Ergebnis.
• Lernen Sie die fünf Failure Modes. Falsches/kein Tool, falsche Argumente, ignorierte Ergebnisse, Loops und zu frühes Stoppen deckt die große Mehrheit der Agent-Fehler ab. Den Modus zu benennen zeigt Ihnen den Fix.
• Bauen Sie jetzt ein kleines Eval Set, nicht später. Zehn bis zwanzig Fälle in einer Tabelle genügen, um zu erkennen, ob eine Änderung geholfen oder still etwas anderes kaputtgemacht hat.
• Bevorzugen Sie verhaltensbezogene Checks gegenüber Wortabgleich. Prüfen Sie, welche Tools aufgerufen wurden und wie oft. Das ist stabiler als die exakte Formulierung zu bewerten, und es fängt die echten Fehler.
• Jeder behobene Fehler wird zu einem Test. Nehmen Sie jeden fehlgeschlagenen Fall in Ihr Eval Set auf, damit er nie still regredieren kann. Ändern Sie eine Sache auf einmal, dann erneut laufen lassen.