Ein Dienstagnachmittag. Zwölf Durchläufe später in einer Debugging-Sitzung, und der Agent behauptete selbstbewusst, dass unser /users-Endpunkt in siebenundvierzig Sekunden antwortete. Die tatsächliche Zahl waren siebenundvierzig Millisekunden.

Probieren Sie Apidog noch heute aus

Ich hatte diesen Fehler zwei Tage lang gesucht. Jede zusätzliche print-Anweisung im MCP-Server verschob die Antwort des Agenten gerade so weit, dass ich dachte, ich käme weiter. Jede Änderung am System-Prompt machte die Antwort plausibler. Nichts davon löste das Problem.

Was ich bis dahin nicht getan hatte: den tatsächlichen Ausführungs-Trace öffnen und prüfen, was zwischen Modell und Tool wirklich übergeben wurde. Genau dafür ist der AI Agent Debugger von Apidog gedacht. Ich hatte ihn drei Wochen zuvor installiert und vergessen. Zwölf Minuten nach dem Öffnen war der Fehler gefunden.

Der Fehler, den ich gejagt hatte

Die Einrichtung war überschaubar:

• ein Agent auf Basis von GPT-5.5
• ein MCP-Server, den ich am Wochenende geschrieben hatte
• ein Tool get_response_time(endpoint), das unsere Metrik-Pipeline abfragte
• ein System-Prompt mit etwa vierzig Wörtern
• der Benutzer-Prompt: „Wie schnell ist der /users-Endpunkt?“

Der Agent antwortete schnell und selbstbewusst, aber falsch. Die Antworten variierten:

• „Der Endpunkt antwortet in 47 Sekunden.“
• „Ungefähr 0,05 Sekunden.“
• „Die Leistung ist akzeptabel.“

Ich hatte die üblichen Dinge ausprobiert:

1. Logging im MCP-Server ergänzt
2. Modellantworten Token für Token gelesen
3. System-Prompts verglichen
4. Testläufe wiederholt
5. Fehlannahmen in einer Notion-Seite gesammelt

Das Problem beim Debugging von Agenten: Der Fehler liegt selten dort, wo man zuerst sucht. Er kann in mehreren Schichten stecken:

• System-Prompt
• Modellauswahl
• Tool-Definition
• Parameter, die das Modell an das Tool übergibt
• Daten, die das Tool zurückgibt
• Interpretation dieser Daten durch das Modell

Ein Konsolenlog zeigt meistens nur eine dieser Ebenen.

Was das Traces-Panel tatsächlich zeigt

Der Apidog-Debugger öffnet sich in drei Spalten:

• links: Sitzungen
• Mitte: Durchläufe
• rechts: Traces

Klicken Sie auf eine Sitzung, zeigt die mittlere Spalte den Dialogverlauf:

• Benutzernachricht
• Modellantwort
• Tool-Aufruf
• Tool-Rückgabe
• nächste Modellantwort

Klicken Sie auf einen Durchlauf, wird rechts der vollständige Ausführungsbaum sichtbar.

Der entscheidende Teil ist der Trace. Er zeigt jeden Schritt in Reihenfolge:

• System-Prompt, wie das Modell ihn empfangen hat
• Benutzer-Prompt, wie das Modell ihn empfangen hat
• Name und Parameter des Tool-Aufrufs als JSON
• Tool-Ergebnis-Payload als JSON
• Modellantwort mit Timing und Token-Daten

Ich öffnete die fehlerhafte Sitzung. Der Tool-Aufruf sah korrekt aus:

get_response_time(endpoint="/users")

Das Modell hatte also das richtige Tool mit dem richtigen Argument ausgewählt.

Dann öffnete ich das Tool-Ergebnis:

{
  "value": 47,
  "p95": 89,
  "samples": 1240
}

Da war der Fehler. Die Metrik-Pipeline gab Werte in Millisekunden zurück. Das Modell nahm Sekunden an. Aus 47 wurde „47 Sekunden“, weil weder Tool-Antwort noch Prompt die Einheit explizit machten.

Das Tool war korrekt. Das Modell interpretierte die Daten falsch. Mein System-Prompt enthielt keine Anweisung zu Einheiten, und die Tool-Antwort enthielt keine Einheiten-Annotation.

Die Korrektur dauerte sechs Zeilen

Ich habe zwei Dinge geändert.

Zuerst die Antwortstruktur im MCP-Server:

{
  "value": { "amount": 47, "unit": "ms" },
  "p95": { "amount": 89, "unit": "ms" },
  "samples": 1240
}

Dann ergänzte ich den System-Prompt um einen Satz:

Tool-Ergebnisse geben Einheiten explizit zurück. Lesen Sie sie sorgfältig.

Danach führte ich denselben /users-Prompt drei weitere Male aus. Drei neue Sitzungen im linken Panel. Alle drei Antworten waren korrekt: Der Endpunkt antwortet in etwa 47 ms.

Die Token-Kosten lagen achtzehn Prozent niedriger als bei meinen fehlgeschlagenen Läufen. Wahrscheinlich, weil das Modell keine zusätzliche Erklärprosa um seine eigenen falschen Annahmen generierte.

Anschließend führte ich denselben Prompt mit Claude Opus 4.7 in einer zweiten Sitzung aus. Gleiche Tool-Konfiguration, gleicher Prompt, anderes Modell. Das Ergebnis war ebenfalls korrekt, aber teurer und etwas ausführlicher. Damit war klar, welches Modell in Produktion gehen würde.

Der eigentliche Wert lag nicht nur im Finden des Fehlers. Der Modellvergleich mit identischen Konfigurationen und zusammenfassenden Metriken im linken Panel war der praktische Teil:

• Durchlaufanzahl
• Schrittanzahl
• Zeit
• Tokens
• Kosten

Diesen Vergleich hatte ich vorher manuell in einer Tabelle gemacht. Im Debugger waren es wenige Klicks.

Was ich falsch gemacht hatte

Die naheliegende Annahme ist: Der AI Agent Debugger ist ein Logging-Tool.

Das ist er nicht.

Logging zeigt, was in einem System passiert ist. Der Debugger zeigt, was Modell und Tool tatsächlich ausgetauscht haben. Das ist die Ebene, auf der viele Agentenfehler entstehen.

Wenn Sie Agenten bauen und nur die Modellausgabe lesen, debuggen Sie nicht den Agenten. Sie debuggen Ihre Hypothese über den Agenten.

Ein Agent ist ein geschlossenes Zusammenspiel aus:

1. Modell
2. Prompt
3. Tools
4. Tool-Antworten

Der Fehler lebt fast immer in einer dieser vier Komponenten oder in der Übergabe zwischen ihnen. Wenn Sie alle vier gleichzeitig sehen, finden Sie Fehler schneller. Wenn nicht, jagen Sie Symptome.

Der Debugger zeigte mir außerdem Nicht-Determinismus in meinem eigenen Agenten. Nach der Korrektur führte ich denselben Prompt fünfmal aus:

• drei Läufe riefen get_response_time einmal auf
• zwei Läufe riefen es zweimal auf
• beim zweiten Aufruf änderte sich die Groß-/Kleinschreibung des Endpunktpfads

Mein Tool-Schema war case-sensitive. Ich hatte das nicht bemerkt, weil meine Testfälle zufällig nur Kleinbuchstaben verwendeten.

Die Mehrfachlauf-Analyse ist deshalb die Funktion, die ich künftig am häufigsten nutzen werde:

1. denselben Prompt fünfmal ausführen
2. Sitzungen im linken Panel vergleichen
3. Unterschiede in Tool-Aufrufen, Parametern und Antwortpfaden prüfen
4. alles absichern, was zwischen den Läufen variiert

Probieren Sie es selbst aus: vollständige Einrichtung

Wenn Sie dieselbe Debugging-Struktur verwenden möchten, gehen Sie so vor.

Schritt 1: Neue Agenten-Debug-Sitzung erstellen

Öffnen Sie Apidog und wechseln Sie oben zum Tab AI Agent Debugger.

Im oberen Bereich konfigurieren Sie Modell und Ausführung:

• Modell-Anbieter links auswählen, z. B. OpenAI oder Anthropic
• konkretes Modell in der Mitte auswählen, z. B. gpt-5.5
• Basis-URL prüfen; sie wird nach Auswahl des Anbieters automatisch ausgefüllt
• auf Run klicken, um eine Sitzung zu starten

Schritt 2: Prompts konfigurieren

Im Tab Prompts gibt es zwei Eingabebereiche.

System Prompt

Hier definieren Sie Rolle, Ziele, Einschränkungen und Tool-Regeln des Agenten.

Beispiel:

Du bist ein API-Debugging-Agent. Nutze verfügbare Tools, um technische Fragen zu beantworten. Wenn Tool-Ergebnisse Einheiten enthalten, übernimm diese Einheiten exakt.

User Prompt

Hier geben Sie die Testeingabe für die aktuelle Sitzung ein.

Beispiel:

Wie schnell ist der /users-Endpunkt?

Klicken Sie anschließend auf Run. Wenn das Eingabefeld nach jedem Lauf automatisch geleert werden soll, aktivieren Sie Clear after Send.

Schritt 3: Tools konfigurieren

Der Tab Tools listet alle Tools auf, die der Agent zur Laufzeit verwenden kann. Die Zahl auf dem Tab zeigt die aktuelle Anzahl verfügbarer oder konfigurierter Tools.

Integrierte Tools

Integrierte Tools werden mit dem Debugger geliefert und können je nach Bedarf aktiviert oder deaktiviert werden.

MCP-Tools

MCP-Tools verbinden den Agenten mit externen Systemen oder benutzerdefinierten Funktionen über MCP-Server.

Unterstützte Verbindungsmethoden:

• STDIO: lokalen MCP-Serverprozess starten
• HTTP: Verbindung zu einem MCP-Server mit Streamable HTTP
• SSE: Verbindung zu einem MCP-Server über Server-Sent Events

Wenn ein MCP-Server Authentifizierung benötigt, konfigurieren Sie Anforderungs-Header oder OAuth 2.0. Nach erfolgreicher Verbindung wählen Sie aus, welche Tools der Server dem Agenten bereitstellt.

Schritt 4: Skills, Authentifizierung und Modellparameter konfigurieren

Drei weitere Tabs vervollständigen die Einrichtung.

Skills

Skills sind wiederverwendbare Workflows für den Agenten. Sie eignen sich für:

• feste Projektabläufe
• wiederkehrende Aufgaben
• gemeinsame Operationsspezifikationen
• weniger lange System-Prompts

Skills werden bei Bedarf zur Laufzeit geladen.

Authentication

Im Tab Authentication hinterlegen Sie Anmeldeinformationen, die Modell- oder MCP-Dienste benötigen.

Settings

Im Tab Settings konfigurieren Sie Modell-Laufzeitparameter wie:

• Temperature
• Max Tokens
• Top P

Welche Parameter unterstützt werden, hängt vom Anbieter ab. Prüfen Sie deshalb, welche Optionen Ihr Modell tatsächlich akzeptiert.

Schritt 5: Die drei Panels lesen

Nach dem Klick auf Run erscheint die neue Sitzung im linken Panel.

Eine Sitzung zeigt eine kompakte Zusammenfassung:

Sitzung 3
1 Durchlauf · 1 Schritt · 10s · 3.1k Tokens · $0.02
gpt-5.5

So lesen Sie die Panels:

• Sitzungs-Panel links: Verlauf aller Ausführungen mit zusammenfassenden Metriken
• Durchlauf-Panel Mitte: einzelne Runden des Benutzer-/Modell-Dialogs
• Traces-Panel rechts: vollständige Ausführungskette des Agenten

Im Traces-Panel sehen Sie unter anderem:

• System- und Benutzer-Prompts
• Modell-Aufrufe
• Denkprozess des Modells, falls vom Modell offengelegt
• MCP-Tool-Aufrufe
• Skill-Ausführungen
• Tool-Eingabeparameter
• Tool-Ergebnisse
• Laufzeit
• Fehlermeldungen
• finale Ausgabe

Wenn ein Tool-Aufruf fehlschlägt oder das Modell eine Ausnahme zurückgibt, ist der fehlerhafte Schritt direkt im Trace sichtbar. Sie müssen nicht in mehreren Logs suchen.

Schritt 6: Modellleistung vergleichen

Für einen sinnvollen Modellvergleich halten Sie alles konstant:

• gleicher Prompt
• gleiche Tool-Konfiguration
• gleiche Authentifizierung
• gleiche Settings, soweit vom Anbieter unterstützt

Dann wechseln Sie nur das Modell und starten einen neuen Lauf. Jede Ausführung erzeugt eine neue Sitzung im linken Panel.

Nützliche Vergleichsmetriken:

• Anzahl der Ausführungsschritte für dieselbe Aufgabe
• Genauigkeit bei der Tool-Auswahl
• Antwortzeit
• Token-Verbrauch
• Kosten
• Stabilität über mehrere Läufe

Ein einfacher Testablauf:

1. Prompt mit Modell A ausführen
2. Prompt mit Modell B ausführen
3. Sitzungen im linken Panel vergleichen
4. Traces öffnen
5. Tool-Aufrufe und Parameter nebeneinander prüfen
6. Kosten, Tokens und Antwortqualität bewerten

Das Fazit

Zwei Tage Debugging reduzierten sich auf zwölf Minuten, weil ich endlich die richtige Ebene gesehen habe: den Austausch zwischen Modell und Tool.

Der Fehler lag nicht im Tool selbst. Er lag nicht in der Modellantwort allein. Er lag in der fehlenden Einheit in der Tool-Payload und in der daraus folgenden Modellinterpretation.

Für Agenten-Debugging heißt das praktisch:

• Tool-Antworten explizit machen
• Einheiten und Formate nicht implizit lassen
• gleiche Prompts mehrfach ausführen
• Tool-Parameter in Traces prüfen
• Modelle mit identischen Setups vergleichen
• nicht nur Ausgaben lesen, sondern Übergaben zwischen Modell und Tool prüfen

Wenn Sie mehr als einen Agenten gebaut haben und den AI Agent Debugger von Apidog noch nicht geöffnet haben, wird einer Ihrer nächsten Fehler wahrscheinlich genau zwischen Modell und Tool liegen.

Laden Sie Apidog herunter und öffnen Sie es beim nächsten Agenten, der eine falsche Antwort mit überzeugender Stimme gibt.

Zwölf Minuten. Siebenundvierzig Millisekunden, nicht siebenundvierzig Sekunden.

Die vollständige Funktionsreferenz, einschließlich MCP-Transport-Setup und Plan-Verfügbarkeit, finden Sie unter Apidog AI Agent Debugger: Verfügbarkeit, Abdeckung und Einrichtung.