1/3+170 XP

Agents evaluieren und debuggen: Traces, Evals und Failure Modes

# 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 bucht selbstbewusst einen Flug nach Boston in Lincolnshire, Großbritannien. Der Kunde wollte Boston, Massachusetts. Die Antwort sieht in Ordnung aus, bis man sieht, was der Agent tatsächlich getan hat: Er hat das Tool zur Auflösung von Flughafencodes nie aufgerufen, also hat er geraten.

Genau in dieser Lücke zwischen „sieht in Ordnung aus" und „was wirklich 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. Er ruft Tools auf (Funktionen wie „Flüge suchen", „Datei lesen" oder „E-Mail senden"), liest die Ergebnisse und entscheidet, was als Nächstes passiert.

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

Ohne Trace ist Debuggen Raten. Mit einem Trace springt der Fehler meist direkt 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 steckt in Step 2. Der Agent hat einen einfachen Städtenamen übergeben und ihn nie disambiguiert. Es gibt keinen „resolve_airport"-Schritt. Das Modell ist nicht beim 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 schlechten 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 müssen? (Ein Klassiker für erfundene „Fakten".)
Schlechte 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 vorwärtszukommen.
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 ergibt.

Woher Traces kommen

Sie bauen sich keinen Trace-Viewer selbst. Moderne Agent-Frameworks erzeugen Traces automatisch, und Observability-Tools zeigen sie als anklickbare Timelines. Offene, kostenlose Optionen sind Langfuse und Arize Phoenix, die beide den OpenTelemetry-Standard unterstützen und damit über Anbieter hinweg 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. Das genaue Setup finden Sie in den Provider-Deep-Dive-Blöcken.

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

python

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 zurück an das Modell geben
    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 können jeden Durchlauf danach erneut abspielen.

Häufige Failure Modes (und was sie behebt)

Wenn Sie einige Dutzend Traces gelesen haben, wiederholen sich die Muster. Hier die großen 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 etwas zu einer Order beantwortest") und, wenn das Framework es erlaubt, einen Tool-Aufruf für diesen Schritt erzwingen.

Falsche Argumentformatierung

Das Tool erwartet ein Datum wie 2026-01-16, der Agent sendet „next Friday". Fix: das Argumentformat klar in der Tool-Beschreibung angeben und einen Validierungsschritt hinzufügen, der falsche Eingaben zurückweist und das Modell zum erneuten Versuch auffordert.

Sich in langen Aufgaben verlieren

Bei einer 15-Schritt-Aufgabe vergisst der Agent bis Schritt 10, was er eigentlich wollte. Fix: die Aufgabe in kleinere Teilaufgaben zerlegen oder jedem Schritt eine kurze Erinnerung an das „aktuelle Ziel" mitgeben.

Zu viele Tool-Aufrufe

Der Agent ruft für eine Frage fünfmal die Websuche auf und verbrennt Zeit und Geld. Fix: ein Step-Limit setzen und ihn anweisen, vor einer weiteren Suche zusammenzufassen, was er schon weiß.

Der Fix ist fast immer eines von drei Dingen: eine klarere Tool-Beschreibung, eine klarere Anweisung oder ein Guardrail (ein Limit oder eine Validierungsprüfung). Ein größeres Modell brauchen Sie selten.

How to Debug AI Agents with Tracing

Watch on YouTube

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 der Checkliste, die ein Pilot vor jedem Flug durchgeht.

Die Kernidee ist ein Eval-Set: eine kleine Sammlung von Testfällen, die Sie jedes Mal laufen lassen, wenn Sie den Agent ändern. Jeder Fall hat einen Input und eine Möglichkeit, den Output zu prüfen.

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

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 man ein Eval-Set laufen lässt

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 gekippt? Ist irgendein Fall von Pass auf Fail gekippt?

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 wütenden 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" gehen beide durch. Dafür gibt es zwei gängige Ansätze:

Verhalten prüfen, nicht Wortwahl. Prüfen Sie, ob 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 ein Rubric zu bewerten („Hat die Antwort die Storno bestätigt? ja/nein"). Nützlich, aber behandeln Sie die Scores als verrauscht, nicht als Evangelium. Machen Sie Stichproben.

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

Wissenscheck

1. Was ist laut Lektion ein Agent-Trace?

2. Warum ist der Agent im Boston-Buchungsbeispiel gescheitert?

3. Was ist der Kerngedanke hinter dem Satz „Sie können nicht reparieren, was Sie nicht sehen"?

MEHRFACHAUSWAHL

4. Wählen Sie ALLE richtigen Antworten. Was erfasst ein Trace typischerweise für einen einzelnen Agent-Durchlauf?

Wählen Sie alle richtigen Antworten aus.

MEHRFACHAUSWAHL

5. Wählen Sie ALLE richtigen Antworten. Welche Aussagen spiegeln die in der Lektion gezogene Unterscheidung zwischen einem Agent und einem einfachen Chatbot wider?

Wählen Sie alle richtigen Antworten aus.

Alles zusammen: der Debug-Loop

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

1. Ein Durchlauf schlägt fehl. 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 ergibt.

3. Failure Mode benennen. Falsches Tool? Schlechte 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 regressiert ist.

6. Den fehlgeschlagenen Fall ins Eval-Set aufnehmen, damit er nie wieder still regressiert.

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, komplett aus echten Fehlern gebaut.

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

Key Takeaways

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 schlechtes Argument oder ein ignoriertes Ergebnis.
Lernen Sie die fünf Failure Modes. Falsches/kein Tool, schlechte 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 reichen, 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 ab.
Jeder behobene Fehler wird ein Test. Nehmen Sie jeden fehlgeschlagenen Fall in Ihr Eval-Set auf, damit er nie still regressieren kann. Ändern Sie eine Sache auf einmal, dann erneut laufen lassen.