Ein Dienstagnachmittag. Zwölf Durchläufe später in einer Debugging-Sitzung, und der Agent teilte mir selbstbewusst mit, dass unser /users-Endpunkt in siebenundvierzig Sekunden antwortete. Die tatsächliche Zahl waren siebenundvierzig Millisekunden.
Ich hatte diesen Fehler zwei Tage lang gejagt. Jedes Mal, wenn ich eine `print`-Anweisung zum MCP-Server hinzufügte, verschob sich die Antwort des Agenten gerade so weit, dass ich dachte, ich käme weiter. Jedes Mal, wenn ich den System-Prompt umschrieb, klang die Antwort plausibler. Nichts davon war richtig.
Was ich bis zu diesem Nachmittag nicht getan hatte, war, den tatsächlichen Ausführungs-Trace zu öffnen und zu sehen, was zwischen dem Modell und dem Tool übergeben wurde. Dafür ist der AI Agent Debugger von Apidog da. Ich hatte ihn drei Wochen zuvor installiert und vergessen. Es dauerte zwölf Minuten, den Fehler zu finden.
Das hat mich überrascht.
Der Fehler, den ich gejagt hatte
Die Einrichtung war einfach. Ein Agent, der auf GPT-5.5 basiert. Ein MCP-Server, den ich an einem Wochenende geschrieben hatte, der ein get_response_time(endpoint)-Tool zur Verfügung stellte, das unsere Metrik-Pipeline abfragte. Ein System-Prompt von vielleicht vierzig Wörtern. Der Benutzer-Prompt: „Wie schnell ist der /users-Endpunkt?“
Der Agent antwortete schnell. Er antwortete selbstbewusst. Er antwortete jedes Mal falsch, auf verschiedene Weisen. Manchmal „der Endpunkt antwortet in 47 Sekunden.“ Manchmal „ungefähr 0,05 Sekunden.“ Einmal, unvergesslich, „die Leistung ist akzeptabel.“
Ich hatte die Dinge getan, die man so tut. Protokollierung zum MCP-Server hinzugefügt. Die Antwort des Modells Token für Token gelesen. System-Prompts verglichen. Geflucht. Am Dienstagmorgen hatte ich drei offene Terminalfenster und eine Notion-Seite mit fehlgeschlagenen Hypothesen.
Das Besondere am Debugging von Agenten ist, dass der Fehler selten dort ist, wo man zuerst sucht. Er kann im System-Prompt liegen, in der Modellauswahl, in der Tool-Definition, in den Parametern, die das Modell an das Tool übergeben hat, in den Daten, die das Tool zurückgegeben hat, oder in der Art und Weise, wie das Modell diese Daten interpretiert hat. Sechs Stellen. Ein Konsolenprotokoll zeigt Ihnen eine davon.
Was das Traces-Panel tatsächlich zeigt
Der Apidog-Debugger öffnet sich in drei Spalten. Sitzungen links. Durchläufe in der Mitte. Traces rechts. Klicken Sie auf eine beliebige Sitzung, und die mittlere Spalte zeigt Ihnen den Dialog: Benutzernachricht, Modellantwort, Tool-Aufruf, Tool-Rückgabe, nächste Modellantwort. Klicken Sie auf einen beliebigen Durchlauf, und die rechte Spalte erweitert sich zum vollständigen Ausführungsbaum darunter.
Der Ausführungsbaum war der Teil, den ich vermisst hatte. Jeder Schritt, der Reihe nach:
- System-Prompt, wie das Modell ihn empfangen hat
- Benutzer-Prompt, wie das Modell ihn empfangen hat
- Name und Parameter des Tool-Aufrufs, als JSON, genau wie das Modell sie ausgegeben hat
- Tool-Ergebnis-Payload, als JSON, genau wie das Tool sie zurückgegeben hat
- Modellantwort, mit Timing und Tokens für den Durchlauf
Ich öffnete die fehlerhafte Sitzung. Der Tool-Aufruf sah gut aus: get_response_time(endpoint="/users"). Das Modell hatte das richtige Tool mit dem richtigen Argument ausgewählt.
Dann erweiterte ich das Tool-Ergebnis.
{"value": 47, "p95": 89, "samples": 1240}
Da war es. Die Metrik-Pipeline gab den Wert in Millisekunden zurück. Das Modell nahm Sekunden an. 47 wurden zu „47 Sekunden“ durch eine selbstbewusste Halluzination, die sich nicht die Mühe machte, die Einheit zu hinterfragen. Das Tool war korrekt. Das Modell war falsch. Mein System-Prompt enthielt keine Anweisung zu Einheiten, und die Tool-Antwort hatte keine Einheiten-Annotation.
Zwölf Minuten nach dem Öffnen des Debuggers. Zwei Tage hatte ich den System-Prompt beschuldigt.
Die Korrektur dauerte sechs Zeilen
Ich habe zwei Dinge geändert. Im MCP-Server habe ich die Antwortstruktur aktualisiert:
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
Dann fügte ich dem System-Prompt einen Satz hinzu: „Tool-Ergebnisse geben Einheiten explizit zurück. Lesen Sie sie sorgfältig.“
Ich führte den gleichen /users-Prompt drei weitere Male aus. Drei verschiedene Sitzungen im linken Panel. Alle drei gaben korrekt „der Endpunkt antwortet in etwa 47 ms“ zurück, mit einer Millisekunden-zu-Perzentil-Aufschlüsselung in der Argumentation des Modells. Die Token-Kosten waren achtzehn Prozent niedriger als bei meinen fehlgeschlagenen Läufen, wahrscheinlich weil das Modell keine Erholungsprosa um seine eigenen schlechten Annahmen herum generierte.
Ich führte denselben Prompt auf Claude Opus 4.7 in einer zweiten Sitzung, nebeneinander, aus. Gleiches Ergebnis, doppelter Preis, etwas wortreicher. Ich wusste, welches Modell in Produktion gehen würde.
Dies ist der Teil des Tools, der meinen Respekt verdiente. Nicht das Fehlerfinden, das jeder anständige Debugger können sollte. Der Modellvergleich, ausgeführt mit identischen Konfigurationen und zusammenfassenden Metriken im linken Panel: Durchlaufanzahl, Schrittanzahl, Zeit, Tokens, Dollar. Ich hatte diesen Vergleich sechs Monate lang in einer Google-Tabelle durchgeführt. Jetzt waren es drei Klicks.
Was ich falsch gemacht hatte
Die einfache Annahme ist, dass der AI Agent Debugger ein Protokollierungstool ist. Das ist er nicht. Protokollierungstools zeigen Ihnen, was passiert ist. Der Debugger zeigt Ihnen, was das Modell und das Tool tatsächlich ausgetauscht haben, was eine andere Ebene ist.
Wenn Sie Agenten schreiben und das getan haben, was ich getan habe, nämlich die Modellausgabe gelesen und die Ursache von Fehlern geraten haben, dann möchte ich Folgendes entgegnen: Sie debuggen nicht den Agenten. Sie debuggen Ihre Hypothese über den Agenten. Das sind unterschiedliche Dinge, und nur eines davon führt Sie zu einer Lösung.
Die Sache, die ich sechs Monate lang nicht verinnerlichen wollte, war, dass der Agent ein geschlossenes System zwischen dem Modell, dem Prompt, den Tools und den Tool-Antworten ist. Der Fehler lebt immer in einem dieser vier Bereiche. Wenn Sie alle vier gleichzeitig sehen können, können Sie den Fehler in zwölf Minuten finden. Wenn nicht, können Sie ihn eine Woche lang jagen.
Die andere Sache, die der Debugger aufdeckte und die ich nicht erwartet hatte, war die Nicht-Determinismus in meinem eigenen Agenten. Ich führte den gleichen Prompt nach der Korrektur fünfmal aus, nur um es zu bestätigen. Drei Läufe riefen get_response_time einmal auf. Zwei Läufe riefen es zweimal auf, das zweite Mal mit dem Endpunktpfad in anderer Groß-/Kleinschreibung. Mein Tool-Schema war Groß-/Kleinschreibung-sensitiv. Ich hatte es nicht bemerkt, weil meine fehlerhaften Testfälle alle zufällig Kleinbuchstaben verwendeten. Das war ein zweiter Fehler, den ich ohne es zu sehen, ausgeliefert hätte.
Die Mehrmalige-Lauf-Analyse ist die Funktion, die ich in Zukunft am häufigsten nutzen werde. Fünfmal auf Ausführen klicken. Das Sitzungs-Panel ansehen. Alles, was zwischen den Läufen variiert, ist ein Bereich, in dem Ihr Agent anfällig ist.
Probieren Sie es selbst aus: Eine vollständige Einrichtungsanleitung
Wenn Sie dieselbe Einrichtung haben möchten, die ich während der Fehlersuche verwendet habe, finden Sie hier den Weg von einer Neuinstallation zu einer laufenden Debug-Sitzung. Fünf Bildschirme, der Reihe nach.
Schritt 1: Eine neue Agenten-Debug-Sitzung erstellen
Öffnen Sie Apidog und klicken Sie in der oberen Registerkartenleiste auf AI Agent Debugger. Der obere Bereich der Seite konfiguriert das Modell und den Ausführungsstatus.
- Wählen Sie den Modell-Anbieter links aus (OpenAI, Anthropic und andere)
- Wählen Sie das spezifische Modell in der Mitte aus, zum Beispiel
gpt-5.5 - Die Basis-URL wird automatisch ausgefüllt, sobald der Anbieter ausgewählt ist, keine manuelle Eingabe erforderlich
- Klicken Sie auf Run, um eine Sitzung zu starten
Schritt 2: Die Prompts konfigurieren
Der Tab Prompts hat zwei Eingabebereiche.
- System Prompt: definiert die Rolle, Ziele, Einschränkungen und Tool-Nutzungsregeln des Agenten
- User Prompt: die Testeingabe für diese Sitzung, zum Beispiel „Was ist Apidog?“
Klicken Sie oben rechts auf Run, wenn beide eingestellt sind. Wenn das Eingabefeld nach jedem Lauf automatisch gelöscht werden soll, aktivieren Sie Clear after Send.
Schritt 3: Die Tools konfigurieren
Der Tab Tools listet alles auf, was der Agent zur Laufzeit aufrufen kann. Die Zahl auf dem Tab ist die aktuelle Anzahl der verfügbaren oder konfigurierten Tools.
Integrierte Tools werden mit dem Debugger geliefert. Schalten Sie sie nach Bedarf ein oder aus.
| Tool | Was es tut |
|---|---|
bash |
Befehle in einer persistenten Shell-Sitzung ausführen |
web_fetch |
Webinhalte abrufen und in Markdown, Text oder HTML konvertieren |
read |
Text-, Bild- oder PDF-Dateien lesen |
edit |
Präzise String-Ersetzungen an Dateien vornehmen |
write |
Dateien erstellen oder überschreiben |
grep |
Dateiinhalte mit regulären Ausdrücken durchsuchen |
glob |
Dateien mit Glob-Mustern finden |
kill_shell |
Die aktuelle Shell-Sitzung zurücksetzen |
MCP-Tools fügen externe Systeme oder benutzerdefinierte Funktionen über MCP-Server hinzu. Drei Verbindungsmethoden:
- STDIO: einen lokalen MCP-Serverprozess starten
- HTTP: sich mit einem MCP-Server verbinden, der Streamable HTTP unterstützt
- SSE: sich mit einem MCP-Server verbinden, der auf Server-Sent Events basiert
MCP-Server, die eine Authentifizierung erfordern, akzeptieren Anforderungs-Header oder OAuth 2.0-Abläufe. Sobald die Verbindung erfolgreich hergestellt wurde, wählen Sie aus, welche Tools der Server dem Agenten zur Verfügung stellt.
Schritt 4: Fähigkeiten, Authentifizierung und Modellparameter konfigurieren
Drei kleinere Tabs runden die Einrichtung ab.
- Skills: wiederverwendbare Workflows für den Agenten. Nützlich für feste Projektworkflows, gemeinsame Aufgabenoperationsspezifikationen und die Reduzierung repetitiver langer Texte in System-Prompts. Skills werden bei Bedarf zur Laufzeit geladen.
- Authentication: Anmeldeinformationen, die von Modell- oder MCP-Diensten benötigt werden.
- Settings: Modell-Laufzeitparameter wie Temperatur, Max Tokens und Top P. Unterstützte Parameter variieren je nach Anbieter, prüfen Sie also, was Ihr Modell tatsächlich akzeptiert.
Schritt 5: Die drei Panels lesen
Nach dem Klicken auf „Run“ erscheint die gerade erstellte Sitzung im linken Panel. Jede Sitzung zeigt eine einzeilige Zusammenfassung:
Sitzung 3
1 Durchlauf · 1 Schritt · 10s · 3.1k Tokens · $0.02
gpt-5.5
- Sitzungs-Panel (links): Verlauf jeder Ausführung mit zusammenfassenden Metriken
- Durchlauf-Panel (Mitte): jede Runde des Benutzer-/Modell-Dialogs. Klicken Sie auf eine Runde, um deren Ausführungsdetails rechts zu laden.
- Traces-Panel (rechts): die vollständige Ausführungskette des Agenten der Reihe nach, einschließlich System- und Benutzer-Prompts, jedes Modell-Aufrufs, des Denkprozesses des Modells (falls vom Modell offengelegt), MCP-Tool-Aufrufen und benutzerdefinierten Skill-Ausführungen, Tool-Eingabeparametern, Ergebnissen, benötigter Zeit, Fehlermeldungen und der endgültigen Ausgabe.
Wenn ein Tool-Aufruf fehlschlägt oder das Modell eine Ausnahme zurückgibt, ist der fehlgeschlagene Schritt direkt im Traces-Panel sichtbar, mit seinen Ein- und Ausgaben. Kein Log-Tauchen.
Schritt 6: Modellleistung vergleichen
Gleicher Prompt, gleiche Tool-Konfiguration, anderes Modell. Jeder Lauf erstellt eine neue Sitzung, und das linke Panel ermöglicht den direkten Vergleich.
Nützliche Metriken zum Vergleichen:
- Anzahl der Ausführungsschritte für dieselbe Aufgabe
- Welches Modell Tools genauer auswählt
- Welches Modell eine geringere Antwortzeit hat
- Welches Modell den Token-Verbrauch und die Kosten vorhersehbarer hält
Das Fazit
Zwei Tage Debugging fielen auf einen Nachmittag zusammen, und ich habe nicht die Lektion über den Fehler gelernt. Ich habe sie über die Tools gelernt. Der Grund, warum ich die falsche Korrektur gejagt hatte, war, dass die Tools, die ich benutzte, mir nicht zeigten, was ich sehen musste. Ich hatte eine Modellausgabe und eine Tool-Ausgabe, und keinen gemeinsamen Rahmen, um sie zusammen zu betrachten. Der gemeinsame Rahmen ist der ganze Punkt.
Wenn Sie mehr als einen Agenten geschrieben haben und den AI Agent Debugger von Apidog noch nicht geöffnet haben, wird der nächste Agent, den Sie ausliefern, einen Fehler haben, der zwischen dem Modell und dem Tool liegt. Sie werden eine Woche damit verbringen. Sie werden eine Notion-Seite mit fehlgeschlagenen Hypothesen schreiben. Der Fehler wird genau dort sein, wo Ihnen der Debugger ihn am ersten Tag gezeigt hätte.
Laden Sie Apidog herunter und öffnen Sie es beim nächsten Agenten, der Ihnen eine falsche Antwort mit selbstbewusster 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.