2026 AI-Agent: Insgesamt fehlerhaftes JSON? Fehler anhand des Datenflusses lokalisieren

August 20, 2026 · CI/CD / DevOps · ca. 11 Min. Lesezeit

Dieser Leitfaden verfolgt fehlerhaftes JSON vom Eingabe-Schema bis zur Tool-Ausführung. Sie erhalten eine priorisierte Prüfkette, eine Vergleichstabelle und eigenständige Antworten auf typische Fehlerbilder in mehrstufigen Agent-Systemen.

Die Tool-Ausführung schlägt fehl, obwohl die Antwort im Log wie JSON aussieht; oft wird dabei ein abgeschnittener Modell-Output direkt an den Parser weitergereicht.

Die schnellste Lösung ist eine Prüfung entlang des vollständigen Datenflusses: Eingabe-Vertrag, Modellgenerierung, API-Status, Parser und Validierung, Tool-Ausführung sowie Ergebnisrückgabe. Ein AI-Agent-JSON-Fehler darf nicht pauschal dem Modell zugeschrieben werden.

Diese Anleitung richtet sich an Backend-Entwickler, die Parsing- und Parameterfehler eingrenzen müssen, an Engineers für mehrstufige Agenten mit verlorenem Kontext sowie an Betriebsteams, die produktive Vorfälle anhand korrelierbarer Logs untersuchen. Wer nur eine einzelne JSON-Antwort aus einem Skript liest und keine Tools aufruft, benötigt wahrscheinlich nicht die gesamte Prüfkette.

Fehlerbild und Datenfluss

Ein typischer Vorfall beginnt mit einer scheinbar klaren Anweisung: Der Agent soll eine Datei prüfen, ein Konto auswählen oder eine Bestellung anlegen. Die Anwendung registriert dafür ein Tool mit einem JSON Schema. Im Betrieb erscheint anschließend eine Meldung wie „unexpected end of JSON input“, „missing required field“ oder „resource not found“. In manchen Fällen ist der Text formal korrekt, aber die nachgelagerte Aktion scheitert trotzdem.

Diese Meldungen liegen auf unterschiedlichen Ebenen:

Das Eingabe-Schema wird vom Anbieter nicht akzeptiert.
Die Modellantwort wird abgelehnt oder vorzeitig beendet.
Streaming-Fragmente werden unvollständig zusammengesetzt.
Der Parser oder Validator interpretiert das Schema anders als die API.
Der Tool-Aufruf ist strukturell korrekt, aber fachlich unbrauchbar.
Beim nächsten Modellschritt fehlen Aufruf-ID, Rolleninformation oder Tool-Ergebnis.

Die Reihenfolge ist entscheidend. Wird zuerst der Prompt umformuliert, obwohl die API die Schema-Definition bereits ablehnt, entsteht nur eine neue Variable im Fehlerbild. Für jede Stufe sollte der Betrieb außerdem festhalten, ob der Fehler deterministisch, eingabebedingt oder nur bei bestimmten Antwortlängen auftritt.

Eingabe-Vertrag und Schema-Kompatibilität

Der erste Prüfschritt gilt dem Vertrag, nicht dem Modell. Ein JSON Schema kann formal gültig sein und trotzdem außerhalb der unterstützten Untermenge eines konkreten Structured-Output- oder Function-Calling-Endpunkts liegen. Zu prüfen sind insbesondere:

deklarierte Schema-Version und $schema-Angabe,
verwendete Datentypen und Format-Schlüssel,
Pflichtfelder und erlaubte zusätzliche Eigenschaften,
verschachtelte Objekte, Arrays und Referenzen,
freie oder uneingeschränkte Wertebereiche,
Unterschiede zwischen Tool-Schema und Antwort-Schema.

Die offizielle JSON-Schema-Spezifikation beschreibt mehrere Dialekte und Entwicklungsstände. Ein Validator, der einen anderen Dialekt als die API erwartet, kann daher ein Ergebnis akzeptieren, das der Anbieter nicht verarbeiten kann. Die Grundlagen zur $schema-Deklaration helfen dabei, die verwendete Variante explizit zu machen, statt sich auf eine Bibliotheksvoreinstellung zu verlassen.

Für die Fehlersuche wird zuerst ein minimales Schema angelegt: ein Objekt mit wenigen Pflichtfeldern, ohne Referenzen, komplexe Bedingungen oder unnötige Formate. Erst wenn dieser Vertrag akzeptiert wird, werden Geschäftsregeln schrittweise ergänzt. So lässt sich unterscheiden, ob die Plattform grundsätzlich funktioniert oder eine einzelne Einschränkung den Request unbrauchbar macht.

Dabei sollten Schema, Tool-Definition und Anwendungsklasse nicht unabhängig versioniert werden. Ein Feld, das in der Datenbank optional ist, kann für den Tool-Aufruf erforderlich sein; umgekehrt kann ein Anbieter zusätzliche Einschränkungen für Pflichtfelder verlangen. Die CI/CD-Pipeline sollte den Vertrag deshalb gegen mindestens den Ziel-Validator und, sofern verfügbar, eine echte Testanfrage an die verwendete API prüfen.

Antwortstatus und Generierung

Ein Parser darf nicht die erste Instanz sein, die eine API-Antwort bewertet. Vor dem Parsen muss der Client feststellen, ob die Antwort erfolgreich, abgelehnt, unvollständig oder technisch fehlgeschlagen ist. Bei Streaming-Implementierungen werden außerdem viele Fragmente erst am Ende zu einem vollständigen Inhalt zusammengesetzt.

Ein getrenntes Statusmodell sollte mindestens folgende Fälle unterscheiden:

erfolgreicher, vollständiger Inhalt,
Refusal oder Sicherheitsablehnung,
Abbruch wegen Längenlimit,
Netzwerk- oder API-Fehler,
unvollständiger Stream,
leerer oder unerwarteter Inhalt.

Die OpenAI-Dokumentation zu Refusal-Deltas in Responses-Streams zeigt, warum eine Ablehnung nicht wie ein normales JSON-Ergebnis behandelt werden darf. Auch bei Gemini nennt die Dokumentation zur Structured-Output-Validierung die Fehlerbehandlung als eigenen Schritt. Ein Client, der den gesamten Antworttext blind an JSON.parse übergibt, vermischt dadurch Transport-, Modell- und Validierungsfehler.

Bei abgeschnittenen Antworten ist ein automatischer Retry nicht grundsätzlich falsch, aber nur bei einer passenden Ursache sinnvoll. Ein erneuter Versuch kann bei einem vorübergehenden Netzwerkfehler helfen; bei einem zu kleinen Ausgabelimit, einem nicht unterstützten Schema oder einer stabilen Ablehnung wiederholt er lediglich denselben Fehler. Das System sollte die Beendigung deshalb vor dem Retry klassifizieren und den Grund im Log speichern.

Parser, Validator und Structured Output

Structured Output verringert das Risiko unstrukturierter Antworten, ersetzt aber nicht die Anwendungsprüfung. Der Anbieter garantiert die gewünschte Form nur innerhalb seiner dokumentierten Fähigkeiten. Die Gemini-Hinweise zu unterstützten Structured-Output-Typen und die OpenAI-Anleitung zu Structured Outputs sollten für den jeweils eingesetzten Endpunkt getrennt geprüft werden.

Ein häufiger Fehler entsteht, wenn Entwicklung und Produktion verschiedene Validatoren oder Bibliotheksversionen verwenden. Der Entwicklungsrechner akzeptiert beispielsweise ein Format-Schlüsselwort, während der Produktionsvalidator es ignoriert oder als ungültig behandelt. Für jedes validierte Ergebnis gehören daher mindestens diese Angaben in den Logdatensatz:

Name und Version des Validators,
verwendeter Schema-Dialekt,
Hash oder Version des Schemas,
API- und SDK-Version,
Validierungsfehler mit Pfad zum betroffenen Feld.

Die Reihenfolge der Prüfungen sollte ebenfalls festgelegt sein:

Ist der API-Status erfolgreich?
Ist der Inhalt vollständig?
Ist der Text syntaktisch gültiges JSON?
Entspricht die Struktur dem JSON Schema?
Sind Werte, Beziehungen und Ressourcen fachlich zulässig?
Darf das Tool mit diesen Parametern ausgeführt werden?

Ein formal gültiges Objekt kann etwa einen leeren Pfad, eine nicht vorhandene Ressource oder eine ungültige Kombination aus Region und Konto enthalten. Diese Regeln gehören nicht ausschließlich in das Schema, weil Existenz und Berechtigung oft erst gegen aktuelle Systeme geprüft werden können.

Function Calling und Tool-Aufrufe

Bei Function Calling ist zwischen dem Funktionsnamen, der Aufrufkennung und den Argumenten zu unterscheiden. Die Gemini-Beschreibung des Function-Calling-Ablaufs macht deutlich, dass das Modell einen Aufruf vorschlägt, die Anwendung das Tool ausführt und das Ergebnis anschließend wieder an den Modellprozess übergibt. Das Modell führt die Funktion nicht automatisch mit den Rechten der Anwendung aus.

Fehlende Parameter werden deshalb in drei Richtungen untersucht:

Das registrierte Schema enthält das Feld nicht oder markiert es falsch.
Der API- oder Streaming-Client verliert Teile der Argumente.
Das Modell erhält die erforderlichen Werte aus dem Kontext nicht.

Vor der Ausführung muss die Anwendung Pflichtfelder, Datentypen, erlaubte Werte und maximale Eingaben prüfen. Danach folgen Berechtigungs- und Existenzprüfungen. Eine Dateioperation benötigt beispielsweise nicht nur einen String als Pfad, sondern einen zulässigen, erreichbaren Pfad und die passende Identität. Bei einer Bestellung müssen Kontostatus, Produktverfügbarkeit und Wertebereich separat geprüft werden.

Bei MCP-gestützten Agenten kommen weitere Zustandsdetails hinzu. Die MCP-Spezifikation für Server-Tools definiert die Beschreibung von Tools und Eingaben; die MCP-Gesamtspezifikation ist für die übergeordneten Austauschregeln relevant. Daraus folgt für den Betrieb: Tool-Metadaten, Aufruf und Ergebnis sollten mit einer gemeinsamen Korrelation protokolliert werden, statt nur den finalen Text zu speichern.

Kontext, Kennungen und Rückgabe

Ein besonders schwerer AI-Agent-JSON-Fehler tritt nach einer scheinbar erfolgreichen Tool-Ausführung auf. Das Tool liefert ein Ergebnis zurück, der nächste Modellschritt reagiert jedoch so, als sei der Aufruf nie erfolgt. In diesem Fall ist nicht zwingend das JSON falsch. Häufig fehlen die ursprüngliche Tool-Call-ID, die Rolleninformation oder ein erforderlicher Verlaufseintrag.

Für mehrstufige Abläufe sollte jeder Übergang explizit geprüft werden:

Die Antwort des Modells wird unverändert archiviert.
Der Tool-Aufruf wird mit Name, Argumenten und Kennung extrahiert.
Das Tool-Ergebnis wird mit derselben Korrelation gespeichert.
Die für den Folgeschritt erforderlichen Nachrichten werden vollständig rekonstruiert.
Die nächste API-Anfrage wird vor dem Versand auf Rollen, Reihenfolge und Referenzen geprüft.

Die Regeln für Zustandsverwaltung unterscheiden sich je nach API-Oberfläche. Deshalb darf ein Implementierungsmuster aus einem Chat-Endpunkt nicht ungeprüft auf eine Responses- oder Streaming-Schnittstelle übertragen werden. Besonders riskant ist die Praxis, nur arguments als JSON zu speichern und den umgebenden Aufruf zu verwerfen. Später lässt sich dann nicht mehr feststellen, welchem Tool und welchem Modellschritt die Daten zugeordnet waren.

Datenschutz und DSGVO-Anforderungen müssen bei diesen Logs von Anfang an berücksichtigt werden. Eingaben, Kontonamen, Dateipfade und Tool-Ergebnisse werden vor der Speicherung maskiert oder gehasht, wenn sie für die Reproduktion nicht vollständig benötigt werden. Ein Log darf für die Korrelation ausreichend detailliert sein, ohne geheime Zugangsdaten oder personenbezogene Inhalte dauerhaft abzulegen.

Eigenständige FAQ zur Fehlerdiagnose

Warum liefert ein AI-Agent immer wieder ungültiges JSON?

Die Ursache liegt nicht automatisch im Modell. Häufig wird bereits ein nicht unterstütztes JSON Schema verwendet, die Antwort wegen eines Längenlimits abgeschnitten oder ein Refusal wie eine normale Textantwort geparst. Prüfen Sie deshalb zuerst Schema-Untermenge und Antwortstatus, danach Parser und erst zuletzt die Modellinstruktion.

Wie lassen sich fehlende Parameter bei Function Calling eingrenzen?

Vergleichen Sie den tatsächlich zurückgegebenen Tool-Aufruf mit dem registrierten Schema und protokollieren Sie den vollständigen Aufruf einschließlich Kennung. Fehlt ein Pflichtfeld, muss außerdem geprüft werden, ob ein Streaming-Delta verloren ging oder der Parser eine andere Schema-Version nutzt. Eine zusätzliche Geschäftsvalidierung bleibt erforderlich.

Warum kann Structured Output trotz aktiviertem Modus fehlschlagen?

Structured Output kontrolliert die Struktur nur innerhalb der vom jeweiligen Anbieter unterstützten Schema-Menge. Eine Ablehnung, abgeschnittene Antwort, nicht unterstützte Funktion oder ein Fehler in der Streaming-Zusammensetzung kann weiterhin auftreten. Der Client muss Status, Refusal und Vollständigkeit getrennt behandeln, bevor er JSON validiert.

Was hilft, wenn nach der Tool-Rückgabe der Gesprächskontext fehlt?

Prüfen Sie, ob die Tool-Call-Kennung, der ursprüngliche Aufruf und das Tool-Ergebnis unverändert an den nächsten Modellschritt übergeben wurden. Bei mehrstufigen APIs gelten unterschiedliche Zustandsregeln. Deshalb sollte die Rückgabe nicht nur als Text gespeichert werden, sondern als strukturierter Datensatz mit Korrelation, Rolleninformation und Aufruf-ID.

Warum ist JSON gültig, obwohl die Geschäftsaktion scheitert?

Syntaktisch gültiges JSON beweist lediglich, dass der Parser eine Datenstruktur bilden kann. Ein Pfad kann fehlen, ein Konto keine Berechtigung besitzen, eine Bestellung außerhalb des zulässigen Bereichs liegen oder eine Ressource nicht existieren. Ergänzen Sie nach der Schema-Prüfung deshalb Existenz-, Berechtigungs-, Wertebereichs- und Beziehungsprüfungen.

Reproduzierbare Diagnose

Für einen produktiven Vorfall sollte das Team nicht mit immer neuen Prompts beginnen, sondern zunächst einen minimalen, reproduzierbaren Datensatz sichern. Die folgenden Schritte bilden eine belastbare Reihenfolge:

Eingabe redigieren: Entfernen oder maskieren Sie personenbezogene Daten, Tokens, interne Pfade und vertrauliche Geschäftswerte, ohne die fehlerauslösende Struktur zu verändern.
Schema einfrieren: Speichern Sie die tatsächlich gesendete Schema-Version, den Dialekt, die Tool-Definition und den Hash der Konfiguration.
Anfrageversion erfassen: Dokumentieren Sie Modellbezeichnung, API-Endpunkt, SDK-Version, Validator-Version und relevante Laufzeitparameter.
Rohantwort sichern: Speichern Sie Status, Stop-Grund, Refusal-Information, Streaming-Fragmente und zusammengeführte Antwort getrennt.
Validierung wiederholen: Führen Sie zuerst einen Syntax-Check, dann die Schema-Prüfung und anschließend die Geschäftsvalidierung aus; jeder Schritt erhält einen eigenen Fehlercode.
Tool isolieren: Testen Sie den Aufruf mit festem, validiertem JSON ohne Modellbeteiligung. Scheitert er weiterhin, liegt die Ursache in Berechtigung, Ressource, API oder Fachlogik.
Rückgabe rekonstruieren: Prüfen Sie, ob Aufruf-ID, Tool-Ergebnis und Kontext vollständig in den nächsten Modellschritt gelangen.
Nur gezielt erneut versuchen: Ein Retry wird nur für klassifizierte, vorübergehende Fehler aktiviert und mit Begrenzung, Korrelation sowie ursprünglichem Fehlergrund protokolliert.

Eine strukturierte Agent-Aufrufprotokollierung sollte dabei nicht nur den finalen Text erfassen. Benötigt werden mindestens Anfrage-ID, übergeordnete Trace-ID, Modellschritt, Tool-Name, Aufruf-ID, Schema-Version, Status, Stop-Grund, Parserfehler, Validierungspfad und Tool-Ergebnis. Für die Fehlerbehebung in einer isolierten Umgebung kann eine temporäre Mac-Testumgebung sinnvoll sein, wenn der Agent lokale Skripte, Entwicklungswerkzeuge oder reproduzierbare Systemzustände benötigt.

Reparaturpriorität nach Fehlerklasse

Die folgende Gegenüberstellung verhindert, dass das Team für jede Meldung dieselbe Maßnahme ausführt:

Fehlerklasse	Erstprüfung	Geeignete Reparatur	Retry-Entscheidung
Schema wird abgelehnt	Dialekt, unterstützte Untermenge, Pflichtfelder	Minimal-Schema senden und schrittweise erweitern	Nein, solange der Vertrag unverändert inkompatibel ist
Antwort ist abgeschnitten	Stop-Grund, Ausgabelimit, vollständige Stream-Fragmente	Limit und Stream-Zusammensetzung prüfen; Ausgabe verkleinern	Nur nach bestätigter transienter Ursache
Refusal oder API-Fehler	Statusfelder und Fehlerobjekt	Eigenen Ablehnungs- oder Fehlerpfad ausführen	Nur bei dokumentiert vorübergehendem Fehler
JSON syntaktisch ungültig	Rohantwort und Parser-Version	Vorparsing, Fragmentzusammenführung und Parser angleichen	Nicht als Standardmaßnahme
JSON Schema ungültig	Validator-Dialekt und Fehlerpfad	Schema, Validator oder Transformationsschritt korrigieren	Nein
Tool-Parameter fachlich ungültig	Existenz, Rechte, Wertebereiche, Feldbeziehungen	Geschäftsvalidierung und sichere Fehlermeldung ergänzen	Nur nach korrigierten Parametern
Kontext oder Aufruf-ID fehlt	Nachrichtenfolge und Korrelation	Vollständigen strukturierten Zustand zurückgeben	Nein, solange der Zustand verloren geht

Die Tabelle trennt Strukturfehler von Ausführungsfehlern. Dadurch wird auch sichtbar, warum „JSON erneut erzeugen“ keine Lösung für fehlende Berechtigungen oder eine nicht existierende Ressource ist. Für Schnittstellenänderungen sollte die Testmatrix bei jedem Wechsel von API, SDK oder Validator erneut ausgeführt werden; die JSON-Schema-Kompatibilitätsprüfung kann dabei als eigener Abnahmeschritt in die Lieferkette eingeplant werden.

Der entscheidende Unterschied zwischen der bisherigen Vorgehensweise und einer stabilen Mac-basierten Diagnoseumgebung liegt in der Reproduzierbarkeit: Eine lokal gewachsene Entwicklungsmaschine enthält oft andere SDK-Versionen, Parser-Voreinstellungen und Berechtigungen als die Produktion. Gemeinsame Testdaten, wechselnde Betriebssystemzustände und schwer nachstellbare lokale Abhängigkeiten verlängern die Ursachenanalyse. Für Teams, die nur vorübergehend eine konsistente Test- oder Fehlerumgebung benötigen, kann die Miete eines Mac über nuvcloud daher praktischer sein als der kurzfristige Kauf zusätzlicher Hardware; für dauerhaft laufende, schwere Workloads oder zwingend benötigte physische Schnittstellen bleibt eine eigene Maschine die ehrlichere Wahl.