Was ist Structured Output? Warum braucht ein AI Agent strukturierte Ausgaben? JSON Schema und gewöhnliches JSON im Vergleich

Fehlerbild: Ein Modell liefert zwar parsebares JSON, aber beim nächsten Lauf heißt customer_id plötzlich customerId, ein Zahlenwert kommt als Text und ein erwartetes Feld fehlt.

Schnellste Lösung: Verwenden Sie für Produktionsdaten und Tool Calling ein explizites Schema mit festen Feldern und Typen. Prüfen Sie die Werte danach trotzdem gegen Geschäftsregeln, Berechtigungen und vorhandene Ressourcen.

Für wen ist dieser Vergleich gedacht?

Dieser Beitrag richtet sich an Entwickler, die Modellantworten an ein Frontend, eine Datenbank, einen Workflow oder einen AI Agent übergeben.

Wenn Sie nur erklärende Texte für Menschen erzeugen, benötigen Sie meist kein strenges Schema. Wenn Ihre Anwendung dagegen automatisch speichert, entscheidet, ein Formular rendert oder ein Werkzeug ausführt, sollten Sie Structured Output gezielt einführen.

Der zentrale Unterschied lautet: Gewöhnliches JSON ist ein Datenformat, JSON Schema ist ein Datenvertrag und Structured Output ist eine Methode, Modellantworten an diesen Vertrag zu binden. Ein AI Agent profitiert davon besonders bei Tool Calling, Zustandsübergaben und maschinell konsumierbaren Endergebnissen. Die Bindung an ein Schema bedeutet jedoch nicht, dass die Inhalte wahr, vollständig oder sicher zur Ausführung sind.

Warum parsebares JSON in der Praxis trotzdem ausfallen kann

Stellen Sie sich eine Rechnungserkennung vor. Ihr Prompt verlangt folgende Antwort:

{
  "invoice_number": "RE-2026-0818",
  "total": 1299.90,
  "currency": "EUR"
}

Die Antwort lässt sich problemlos parsen. Beim nächsten Dokument erhalten Sie jedoch:

{
  "invoiceNo": "RE-2026-0819",
  "total": "1.299,90 €",
  "currency": "Euro",
  "supplier": {
    "name": "Beispiel GmbH"
  }
}

Syntaktisch ist dieses Objekt gültig. Für Ihre Anwendung kann es dennoch unbrauchbar sein. Mindestens vier Probleme entstehen:

• Felddrift: invoice_number und invoiceNo bedeuten vermutlich dasselbe, sind für einen strikten Parser aber unterschiedliche Schlüssel.
• Typdrift: Der Betrag war zunächst eine Zahl und wird danach als formatierter Text geliefert.
• Wertevariation: EUR wird zu Euro, obwohl ein nachgelagerter Prozess möglicherweise nur einen ISO-Code akzeptiert.
• Ungeplante Erweiterung: Ein zusätzliches Objekt kann zwar harmlos wirken, aber Datenbankmapping, Typdefinitionen oder Frontend-Komponenten stören.

Bei manueller Prüfung fällt ein solches Problem oft sofort auf. In einer nächtlichen Batch-Verarbeitung, einem Zahlungsworkflow oder einem Agentenlauf wird es dagegen möglicherweise erst an einer späteren Stelle sichtbar. Dann ist die Fehlersuche teurer, weil Sie nicht mehr sicher wissen, ob das Modell, der Parser, die Datenbank oder ein Tool die Abweichung verursacht hat.

Ein weiterer versteckter Kostenfaktor ist die uneinheitliche Fehlerbehandlung. Wenn Ihre Anwendung für jede neue Schreibweise Sonderfälle ergänzt, wächst die sogenannte Toleranzlogik. Sie akzeptiert dann immer mehr Varianten, ohne eindeutig zu wissen, welche Daten tatsächlich gültig sind. Das kann kurzfristig Ausfälle vermeiden, verschlechtert aber langfristig Datenqualität, Monitoring und Wartbarkeit.

Die drei Ebenen: JSON, JSON Schema und Structured Output

JSON beschreibt, wie Daten serialisiert werden. Ein Objekt mit Schlüssel-Wert-Paaren, eine Liste, eine Zeichenkette, eine Zahl, ein boolescher Wert oder null kann gültiges JSON sein. JSON schreibt jedoch nicht automatisch vor, welche Felder Ihre Anwendung erwartet.

JSON Schema beschreibt dagegen welche JSON-Daten zulässig sind. Die offizielle Spezifikation trennt unter anderem grundlegende Schemaelemente von Validierungsregeln; aktuell wird der Dialekt 2020-12 als maßgebliche Spezifikationsversion geführt. Zur offiziellen JSON-Schema-Spezifikation

Ein vereinfachtes Schema für die Rechnung könnte so aussehen:

{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": "string"
    },
    "total": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "enum": ["EUR", "USD", "GBP"]
    }
  },
  "required": ["invoice_number", "total", "currency"],
  "additionalProperties": false
}

Dieses Schema ist selbst ein JSON-Dokument. Es ist aber nicht die Rechnung, sondern die formale Beschreibung einer erlaubten Rechnung. Deshalb ist die Antwort auf die häufige Verwechslung eindeutig: JSON Schema ist in JSON geschrieben, aber nicht mit der eigentlichen JSON-Nutzlast gleichzusetzen.

Structured Output bezeichnet die Ausgabefunktion einer Modell-API, bei der Sie ein Schema oder eine vergleichbare Strukturvorgabe an die Generierung übergeben. Das Modell soll dann nicht nur „irgendwie JSON“ erzeugen, sondern eine Antwort, die der erwarteten Struktur entspricht. Anbieter unterscheiden sich dabei in unterstützten Schlüsselwörtern, Fehlermodi, Modellabdeckung und Garantien. Sie sollten deshalb immer die jeweilige offizielle Dokumentation prüfen.

Wichtig: Eine schema-konforme Antwort kann fachlich falsch sein. Ein Modell kann eine gültige Zahl, ein gültiges Datum oder eine zulässige Enum-Option ausgeben, obwohl der Wert nicht zur Realität Ihrer Anwendung passt.

Welche Ausgabe passt zu welchem Verbrauchszweck?

Die Auswahl sollte nicht beim Modell beginnen, sondern beim Verbraucher der Antwort. Fragen Sie zuerst, wer die Daten liest und welche Folgen eine Abweichung hat.

Für eine interne Statistikmeldung mit wenigen Folgen kann gewöhnliches JSON genügen. Für eine Rechnung, einen Datenbankeintrag oder einen Werkzeugaufruf ist diese Entscheidung meist zu locker. Besonders kritisch wird es, wenn ein AI Agent selbständig Aktionen vorbereitet: Ein formal korrektes Objekt ist dann nur der erste Kontrollpunkt.

Structured Output im Datenextraktionsprozess

Bei der Extraktion sollten Sie drei Stufen unterscheiden:

1. JSON im Prompt verlangen: Sie bitten das Modell, ausschließlich JSON auszugeben.
2. JSON mode verwenden: Die Schnittstelle unterstützt eine JSON-Ausgabe, die typischerweise syntaktisch parsebar sein soll.
3. Structured Output mit Schema nutzen: Sie definieren Felder, Typen und gegebenenfalls erlaubte Werte als Vertrag.

Die erste Stufe ist für Prototypen oder einmalige Experimente oft ausreichend. Sie hängt stark von Prompt, Modellverhalten und Fehlerbehandlung ab. JSON mode reduziert das Risiko von Text außerhalb des Objekts, sagt aber nicht automatisch, dass total eine Zahl ist, currency einem festen Set entspricht oder jedes Pflichtfeld vorhanden ist. Die Dokumentation einer Schnittstelle kann zusätzlich eigene Einschränkungen nennen; bei OpenAI wird etwa zwischen dem älteren json<em>object-Verfahren und dem empfohlenen json</em>schema-Format für unterstützte Modelle unterschieden. Zur offiziellen Beschreibung der Antwortformate

Für feste Produktionsdaten ist ein Schema die bessere Ausgangsbasis, wenn die verwendete API die benötigten Regeln tatsächlich unterstützt. Google beschreibt für Structured Output ausdrücklich eine Teilmenge von JSON Schema und weist darauf hin, dass syntaktisch korrektes JSON weiterhin fachlich validiert werden muss. Zur offiziellen Gemini-Dokumentation für Structured Output

Das bedeutet für Ihre Implementierung:

• Definieren Sie Pflichtfelder nur dort, wo ein Fehlen tatsächlich ein Fehler ist.
• Verwenden Sie enum, wenn der Wertebereich klein und geschlossen ist.
• Trennen Sie Anzeigeformat und Speicherformat, etwa eine numerische Summe von einer lokal formatierten Währungsausgabe.
• Setzen Sie additionalProperties bewusst ein, statt unbekannte Felder stillschweigend zu akzeptieren.
• Speichern Sie Schema-Version und Modellkennung gemeinsam mit dem Ergebnis.
• Behandeln Sie Ablehnungen, unvollständige Antworten und Validierungsfehler als eigene Zustände.

Ein kleiner Unterschied mit großer Wirkung

Ein Prompt wie „Geben Sie das Datum im Format TT.MM.JJJJ aus“ beschreibt eine Erwartung in natürlicher Sprache. Ein Schema mit type: "string" und format: "date" beschreibt dagegen eine maschinenlesbare Bedingung. Allerdings unterstützt nicht jede Modell-API jedes JSON-Schema-Schlüsselwort gleich. Ein universelles Schema für mehrere Anbieter kann daher nur die gemeinsame Teilmenge verwenden oder pro Anbieter eine angepasste Fassung benötigen.

Die offizielle JSON-Schema-Dokumentation erklärt JSON Schema als deklarative Sprache zur Beschreibung und Validierung von Struktur, Einschränkungen und Datentypen. Für die Anwendung reicht es jedoch nicht, ein Schema zu schreiben: Sie brauchen auch einen Validator und einen klar definierten Umgang mit Abweichungen.

Tool Calling braucht zwei Prüfungen, nicht nur ein Schema

Tool Calling unterscheidet sich vom Structured Output durch den Zweck. Structured Output formt in erster Linie eine Antwort. Tool Calling soll dagegen einen konkreten Werkzeugaufruf vorbereiten oder auslösen.

Ein Werkzeug könnte beispielsweise folgende Parameter erwarten:

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string"
    },
    "environment": {
      "type": "string",
      "enum": ["staging", "production"]
    },
    "restart": {
      "type": "boolean"
    }
  },
  "required": ["project_id", "environment", "restart"],
  "additionalProperties": false
}

Die Schema-Prüfung beantwortet nur: Hat die Eingabe die richtige Form? Sie beantwortet nicht:

• Existiert das Projekt tatsächlich?
• Darf dieser Benutzer die Produktionsumgebung ändern?
• Ist ein Neustart zu diesem Zeitpunkt zulässig?
• Ist die angeforderte Ressource gesperrt?
• Enthält project_id zwar einen gültigen String, aber einen schädlichen oder fremden Wert?

Vor der Ausführung sollten Sie deshalb mindestens fünf Schritte durchlaufen:

1. Antwort empfangen: Extrahieren Sie Werkzeugname, Aufruf-ID und Parameter.
2. Schema validieren: Prüfen Sie Datentypen, Pflichtfelder, Enum-Werte und unbekannte Eigenschaften.
3. Identität und Berechtigung prüfen: Ordnen Sie die Aktion einem authentifizierten Benutzer, Dienstkonto oder Auftrag zu.
4. Geschäftsregeln und Ressourcen prüfen: Fragen Sie Datenbank, Inventar oder Statussystem ab.
5. Ausführen und protokollieren: Begrenzen Sie Zeit, Umfang und Seiteneffekte; speichern Sie Ergebnis und Aufruf-ID.

Auch andere Schnittstellen verwenden JSON Schema für Werkzeugparameter. In der Tool-Use-Dokumentation wird input_schema als Beschreibung der erwarteten Werkzeugeingabe eingesetzt. Zur offiziellen Tool-Use-Dokumentation

Vorteile und Grenzen im Werkzeugkontext

Vorteile:

• Der Werkzeugadapter erhält eine klar definierte Eingabestruktur.
• Parserfehler lassen sich vor der eigentlichen Aktion erkennen.
• Monitoring kann nach Werkzeugname, Status und Aufruf-ID gruppieren.
• Berechtigungen können an Werkzeug und Parameter gekoppelt werden.

Grenzen:

• Ein gültiger String kann auf eine falsche oder fremde Ressource zeigen.
• Ein erlaubter Enum-Wert kann im aktuellen Geschäftsprozess unzulässig sein.
• Ein Modell kann eine gefährliche Aktion formal korrekt anfordern.
• Ein Schema verhindert keine Prompt-Injection in der Werkzeugbeschreibung oder im übergebenen Inhalt.

Für produktive Agenten ist daher eine Architektur mit „Schema plus Policy“ sinnvoll: Das Schema beschreibt den Datentyp, die Policy beschreibt, ob und unter welchen Bedingungen die Aktion stattfinden darf.

Dynamische Oberflächen benötigen Versionen und Rückfallebenen

Ein AI Agent kann nicht nur Daten extrahieren, sondern auch Formulare, Karten oder Dialogelemente beschreiben. Ein Frontend könnte etwa aus einem strukturierten Ergebnis eine Texteingabe, eine Auswahlbox und einen Bestätigungsbutton erzeugen.

Das ist attraktiv, weil Backend und Modell nicht für jede neue Oberfläche einen vollständig neuen Endpunkt benötigen. Gleichzeitig entsteht ein Kopplungsrisiko: Eine Änderung am Schema kann ältere Clients überraschen. Wird label in title umbenannt, options von einer Liste zu einem Objekt verändert oder ein Pflichtfeld ergänzt, kann die Darstellung fehlschlagen.

Für dynamische Benutzeroberflächen sollten Sie deshalb:

• eine sichtbare Schema-Version führen;
• neue Felder zunächst optional einführen;
• sinnvolle Standardwerte definieren;
• unbekannte Felder ignorieren können, wenn dies sicher ist;
• kritische Änderungen über eine neue Version ausrollen;
• immer eine lesbare Textantwort als Rückfallebene behalten;
• keine Aktion allein deshalb aktivieren, weil das Frontend sie rendern konnte.

Die Oberfläche ist dabei nicht der einzige Verbraucher. Auch Telemetrie, Cache-Schlüssel, Datenbankmigrationen und externe Integrationen können vom Schema abhängen. Prüfen Sie daher nicht nur, ob das JSON validiert, sondern ob jede beteiligte Komponente mit der neuen Version umgehen kann.

Zwischenzustand und Endantwort eines AI Agenten

In einem mehrstufigen Agenten-Workflow gibt es mindestens zwei unterschiedliche Kommunikationsarten. Der Zwischenzustand beschreibt, was der Agent gerade versucht: Werkzeug auswählen, Aufruf senden, Ergebnis empfangen, Rückfrage stellen oder auf eine Freigabe warten. Die Endantwort erklärt dem Benutzer, was erreicht wurde oder warum ein Vorgang nicht abgeschlossen werden konnte.

Diese Ebenen sollten Sie nicht in ein einziges überladenes JSON-Objekt pressen. Für Ereignisse sind beispielsweise event<em>type, run</em>id, tool<em>call</em>id, status, payload und schema<em>version sinnvoll. Für die Endantwort können zusätzlich answer, citations, warnings und next</em>action vorgesehen werden. Ein verständlicher Text darf parallel enthalten sein, damit der Benutzer nicht die interne Ereignisstruktur lesen muss.

Vermeiden Sie außerdem, interne Gedankengänge als Pflichtfelder zu modellieren. Für die Systemintegration brauchen Sie beobachtbare Zustände, verwendete Werkzeuge, Eingaben, Ergebnisse und Fehlercodes — nicht die vollständige interne Argumentation des Modells. Das reduziert Datenschutzrisiken und verhindert, dass eine unnötige interne Struktur zum öffentlichen API-Vertrag wird.

Ein robustes Muster sieht so aus:

Ereignis 1: agent_started
Ereignis 2: tool_requested
Ereignis 3: tool_validated
Ereignis 4: tool_executed
Ereignis 5: final_response

Jedes Ereignis kann ein eigenes, kleines Schema besitzen. Die finale Antwort darf anschließend strukturiert und zugleich menschenlesbar sein. Dadurch können Workflow-Engine und Frontend unabhängig voneinander arbeiten.

FAQ: Die fünf Abgrenzungen, die in Projekten am häufigsten fehlen

Die folgenden Antworten sind besonders relevant, wenn Sie einen bestehenden Prototypen in eine belastbare Anwendung überführen.

Structured Output und JSON mode

JSON mode ist vor allem eine Formatvorgabe: Die Antwort soll als JSON vorliegen. Structured Output beschreibt zusätzlich, welche Struktur dieses JSON erfüllen soll. Das ist ein qualitativer Unterschied bei Pflichtfeldern, Datentypen und kontrollierten Werten. Dennoch bleiben Anbieterunterschiede wichtig, weil ein Schema-Schlüsselwort möglicherweise nicht unterstützt wird oder nur innerhalb einer dokumentierten Teilmenge funktioniert.

JSON Schema und JSON

JSON Schema ist keine alternative Serialisierung zu JSON. Es wird zwar selbst als JSON-Dokument geschrieben, beschreibt aber andere JSON-Dokumente. Ein Schema kann festlegen, dass ein Feld eine Zahl sein muss, dass bestimmte Felder erforderlich sind oder dass nur bestimmte Zeichenketten erlaubt sind. Erst ein Validator prüft eine konkrete Nutzlast gegen diese Regeln.

Warum ein AI Agent nicht nur gewöhnliches JSON ausgeben sollte

Ein AI Agent reicht Informationen häufig an Systeme weiter, die keine sprachliche Interpretation durchführen. Schon kleine Feld- oder Typabweichungen können dann einen Lauf stoppen oder falsche Zustände erzeugen. Gewöhnliches JSON ist für lose Kopplung brauchbar, aber für produktive Werkzeugparameter und kritische Zustandsübergaben zu wenig verbindlich. Deshalb sollte der Agent dort ein enges Schema verwenden.

Schema-Konformität und inhaltliche Wahrheit

Ein Schema prüft die Form, nicht die Quelle oder Richtigkeit des Inhalts. 2026-08-18 kann ein korrekt formatiertes Datum sein, obwohl es für den konkreten Auftrag falsch ist. Eine Kundennummer kann dem erwarteten Muster entsprechen, ohne in Ihrem System zu existieren. Inhaltliche Richtigkeit erfordert Quellenabgleich, Datenbankprüfung, Plausibilitätsregeln und eine angemessene Freigabelogik.

Tool-Parameter und finale Antwort

Beide Ausgaben können ein Schema benötigen, müssen aber nicht dasselbe Schema verwenden. Werkzeugparameter sollten minimal, streng und sicherheitsorientiert sein. Die finale Antwort braucht dagegen häufig Erklärtext, Warnungen oder Verweise. In einem AI Agenten sollten Sie daher Werkzeugvertrag und Benutzerantwort getrennt versionieren, statt eine einzige Struktur für alle Zwecke zu erzwingen.

Ein fünfstufiges Einführungsmodell für Ihre Anwendung

Wenn Sie bisher nur Prompt-basiertes JSON verwenden, müssen Sie nicht sofort den gesamten Agenten umbauen. Gehen Sie kontrolliert vor:

1. Verbraucher dokumentieren: Notieren Sie für jeden Modellaufruf, ob Mensch, Frontend, Datenbank, Workflow oder Werkzeug die Antwort konsumiert.
2. Fehlerfolgen klassifizieren: Trennen Sie kosmetische Abweichungen von Fehlern, die Geldbewegungen, Berechtigungen, Produktionssysteme oder Datenverlust betreffen.
3. Kleinstes sinnvolles Schema erstellen: Beginnen Sie mit Pflichtfeldern, Datentypen und wenigen Enums. Ein zu kompliziertes Schema ist schwerer kompatibel zu halten.
4. Vier Varianten vergleichen: Testen Sie dieselbe Extraktionsaufgabe mit natürlicher Sprache, Prompt-JSON, JSON mode und strengem Schema. Protokollieren Sie Modell, Schnittstelle, Datum, Fehlertyp und Validierungsergebnis.
5. Nach dem Modellaufruf erneut validieren: Führen Sie Ihre eigene Schema- und Geschäftsprüfung aus, bevor Sie Daten speichern oder Werkzeuge ausführen.

Für langfristige Batch-Verarbeitung sollten Sie zusätzlich eine stabile Ausführungsumgebung einplanen. Reproduzierbare Abhängigkeiten, kontrollierte Laufzeit, ausreichender Arbeitsspeicher, Protokollierung und ein klarer Wiederholungsmechanismus sind oft wichtiger als die reine Modellantwort. Informationen zur Planung und Kontaktaufnahme können Sie im deutschen Hilfezentrum von kvmboot nachschlagen; bei projektspezifischen Fragen steht auch die deutsche Kontaktseite von kvmboot zur Verfügung.

Die Entscheidung nach Verbrauchszweck

Die einfachste Regel lautet:

• Menschen lesen: natürliche Sprache.
• Systeme tauschen lose Daten aus: gewöhnliches JSON, sofern Fehler tolerierbar sind.
• Produktionsdaten werden gespeichert: Structured Output mit JSON Schema und anschließender Geschäftsvalidierung.
• Ein Werkzeug wird aufgerufen: Tool Calling mit engem Parameter-Schema, Autorisierung und Ressourcenprüfung.
• Mehrere Agentenschritte laufen: versionierte Ereignisschemata für Zwischenzustände und ein separates Format für die Endantwort.

Verwechseln Sie dabei nicht Stabilität mit Wahrheit. Structured Output kann Parser- und Integrationsfehler verringern, aber keine veraltete Datenquelle, fehlerhafte Geschäftslogik oder fehlende Berechtigung reparieren. Auch die konkrete Unterstützung von JSON Schema ist je nach Anbieter und Modell begrenzt; bei Gemini wird beispielsweise ausdrücklich auf unterstützte Schema-Teilbereiche und mögliche Einschränkungen bei großen oder tief verschachtelten Schemata hingewiesen. Zu den dokumentierten Einschränkungen bei Structured Output

Wenn Sie lediglich gelegentlich eine Antwort aus einem Chat kopieren, wäre ein strenger Vertrag unnötige Komplexität. Wenn jedoch jede Nacht Tausende Datensätze extrahiert, Werkzeuge ausgeführt oder Zustände zwischen Agentenschritten übertragen werden, lohnt sich eine eigene Test- und Laufzeitumgebung. Eine lokale Installation ist dann nicht immer die beste kurzfristige Lösung: Hardware muss verfügbar sein, Updates können reproduzierbare Läufe stören und bei wechselnder Auslastung bleibt ein Teil der Kapazität ungenutzt. Auch eine beliebige Cloud-Umgebung kann durch schwankende Latenz, fehlende Kontrolle über Abhängigkeiten oder unklare Zugriffsgrenzen unpraktisch werden.

Für zeitlich begrenzte Extraktionsaufgaben, Tool-Tests oder die Abnahme eines mehrstufigen Workflows kann es daher sinnvoller sein, eine dedizierte Mac-Umgebung von kvmboot zu mieten und dort Schema-Tests, Validierung und Monitoring unter reproduzierbaren Bedingungen durchzuführen. Für dauerhaft konstante Schwerlast oder Anwendungen mit speziellen physischen Schnittstellen bleibt der Kauf eigener Hardware die ehrlichere Entscheidung. Entscheidend ist, ob Sie gerade dauerhaft Kapazität besitzen müssen oder eine kontrollierte Umgebung für Entwicklung, Abnahme und wechselnde Agentenläufe benötigen.