Strukturierte Ausgaben

Strukturierte Ausgaben (structured outputs) beschränken Claudes Antworten darauf, einem bestimmten Schema zu folgen, und stellen so gültige, parsbare Ausgaben für die nachgelagerte Verarbeitung sicher. Strukturierte Ausgaben bieten zwei sich ergänzende Funktionen:

• JSON-Ausgaben (output_config.format): Erhalte Claudes Antwort in einem bestimmten JSON-Format
• Strikte Tool-Nutzung (strict: true): Garantiere Schema-Validierung für Tool-Namen und -Eingaben

Du kannst diese Funktionen unabhängig voneinander oder zusammen in derselben Anfrage verwenden.



Warum strukturierte Ausgaben verwenden

Ohne strukturierte Ausgaben kann Claude fehlerhafte JSON-Antworten oder ungültige Tool-Eingaben generieren, die deine Anwendungen zum Absturz bringen. Selbst mit sorgfältigem Prompting können folgende Probleme auftreten:

• Parsing-Fehler durch ungültige JSON-Syntax
• Fehlende Pflichtfelder
• Inkonsistente Datentypen
• Schema-Verletzungen, die Fehlerbehandlung und Wiederholungsversuche erfordern

Strukturierte Ausgaben garantieren schemakonforme Antworten durch „constrained decoding" (eingeschränktes Dekodieren):

• Immer gültig: Keine JSON.parse()-Fehler mehr
• Typsicher: Garantierte Feldtypen und Pflichtfelder
• Zuverlässig: Keine Wiederholungsversuche wegen Schema-Verletzungen nötig



JSON-Ausgaben

JSON-Ausgaben steuern Claudes Antwortformat und stellen sicher, dass Claude gültiges JSON zurückgibt, das deinem Schema entspricht. Verwende JSON-Ausgaben, wenn du Folgendes benötigst:

• Claudes Antwortformat steuern
• Daten aus Bildern oder Text extrahieren
• Strukturierte Berichte generieren
• API-Antworten formatieren



Schnellstart

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
print(response.content[0].text)

Antwortformat: Gültiges JSON, das deinem Schema entspricht, in response.content[0].text

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}



So funktioniert es



Arbeiten mit JSON-Ausgaben in SDKs

Die SDKs bieten Helfer, die die Arbeit mit JSON-Ausgaben erleichtern, einschließlich Schema-Transformation, automatischer Validierung und Integration mit beliebten Schema-Bibliotheken.



Verwendung nativer Schema-Definitionen

Anstatt rohe JSON-Schemas zu schreiben, kannst du vertraute Schema-Definitionswerkzeuge in deiner Sprache verwenden:

• Python: Pydantic-Modelle mit client.messages.parse()
• TypeScript: Zod-Schemas mit zodOutputFormat() oder typisierte JSON-Schema-Literale mit jsonSchemaOutputFormat()
• Java: Einfache Java-Klassen mit automatischer Schema-Ableitung über outputConfig(Class<T>)
• Ruby: Anthropic::BaseModel-Klassen mit output_config: {format: Model}
• PHP: Klassen, die StructuredOutputModel implementieren, mit outputConfig: ['format' => MyClass::class]
• C#: Einfache C#-Klassen mit der generischen Create<T>()-Überladung, die das Schema automatisch ableitet
• Go: Go-Structs, die auf der Beta-API automatisch in JSON-Schemas reflektiert werden, oder rohe JSON-Schemas über output_config
• CLI: Rohe JSON-Schemas, die über output_config übergeben werden

from pydantic import BaseModel
from anthropic import Anthropic


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)



SDK-spezifische Methoden

Jedes SDK bietet Helfer, die die Arbeit mit strukturierten Ausgaben erleichtern. Siehe die einzelnen SDK-Seiten für vollständige Details.



Wie die SDK-Transformation funktioniert

Die Python-, TypeScript-, Ruby- und PHP-SDKs transformieren Schemas mit nicht unterstützten Funktionen automatisch. Die C#- und Go-SDKs wenden dieselben Transformationen an, wenn das Schema aus einem nativen Typ abgeleitet wird (Create<T>() in C#; Struct-Reflexion oder BetaJSONSchemaOutputFormat() auf der Go-Beta-API). Die Transformationsschritte:

1. Entfernen nicht unterstützter Constraints (zum Beispiel minimum, maximum, minLength, maxLength)
2. Aktualisieren der Beschreibungen mit Constraint-Informationen (zum Beispiel „Must be at least 100"), wenn der Constraint nicht direkt mit strukturierten Ausgaben unterstützt wird
3. Hinzufügen von additionalProperties: false zu allen Objekten
4. Filtern von String-Formaten auf die unterstützte Liste
5. Validieren der Antworten gegen dein ursprüngliches Schema (mit allen Constraints)

Das bedeutet, Claude erhält ein vereinfachtes Schema, aber dein Code erzwingt weiterhin alle Constraints durch Validierung.

Beispiel: Ein Pydantic-Feld mit minimum: 100 wird im gesendeten Schema zu einem einfachen Integer, aber das SDK aktualisiert die Beschreibung auf „Must be at least 100" und validiert die Antwort gegen den ursprünglichen Constraint.



Häufige Anwendungsfälle



Strikte Tool-Nutzung

Zur Erzwingung der JSON-Schema-Konformität bei Tool-Eingaben mit grammatikbeschränktem Sampling siehe Strikte Tool-Nutzung.



Beide Funktionen zusammen verwenden

JSON-Ausgaben und strikte Tool-Nutzung lösen unterschiedliche Probleme und funktionieren zusammen:

• JSON-Ausgaben steuern Claudes Antwortformat (was Claude sagt)
• Strikte Tool-Nutzung validiert Tool-Parameter (wie Claude deine Funktionen aufruft)

In Kombination kann Claude Tools mit garantiert gültigen Parametern aufrufen UND strukturierte JSON-Antworten zurückgeben. Das ist nützlich für agentische Workflows, bei denen du sowohl zuverlässige Tool-Aufrufe als auch strukturierte finale Ausgaben benötigst.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON-Ausgaben: strukturiertes Antwortformat
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # Strikte Tool-Nutzung: garantierte Tool-Parameter
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)



Wichtige Überlegungen



Grammatik-Kompilierung und Caching

Strukturierte Ausgaben verwenden eingeschränktes Sampling mit kompilierten Grammatik-Artefakten. Dies bringt einige Leistungsmerkmale mit sich, die du beachten solltest:

• Latenz bei der ersten Anfrage: Beim ersten Verwenden eines bestimmten Schemas entsteht zusätzliche Latenz, während die Grammatik kompiliert wird
• Automatisches Caching: Kompilierte Grammatiken werden für 24 Stunden ab der letzten Verwendung zwischengespeichert, wodurch nachfolgende Anfragen deutlich schneller werden
• Cache-Invalidierung: Der Cache wird invalidiert, wenn du Folgendes änderst:
  • Die JSON-Schema-Struktur
  • Die Menge der Tools in deiner Anfrage (bei Verwendung von strukturierten Ausgaben und Tool-Nutzung)
  • Das Ändern nur der Felder name oder description invalidiert den Cache nicht



Prompt-Modifikation und Token-Kosten

Bei der Verwendung strukturierter Ausgaben erhält Claude automatisch einen zusätzlichen System-Prompt, der das erwartete Ausgabeformat erklärt. Das bedeutet:

• Deine Eingabe-Token-Anzahl ist etwas höher
• Der eingefügte Prompt kostet dich Token wie jeder andere System-Prompt
• Das Ändern des Parameters output_config.format invalidiert jeden Prompt-Cache für diesen Konversations-Thread



JSON-Schema-Einschränkungen

Strukturierte Ausgaben unterstützen Standard-JSON-Schema mit einigen Einschränkungen. Sowohl JSON-Ausgaben als auch strikte Tool-Nutzung teilen diese Einschränkungen.



Eigenschaftsreihenfolge

Bei der Verwendung strukturierter Ausgaben behalten Eigenschaften in Objekten ihre im Schema definierte Reihenfolge bei, mit einer wichtigen Einschränkung: Pflichteigenschaften erscheinen zuerst, gefolgt von optionalen Eigenschaften.

Zum Beispiel bei diesem Schema:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Die Ausgabe ordnet die Eigenschaften wie folgt:

1. name (erforderlich, in Schema-Reihenfolge)
2. email (erforderlich, in Schema-Reihenfolge)
3. notes (optional, in Schema-Reihenfolge)
4. age (optional, in Schema-Reihenfolge)

Das bedeutet, die Ausgabe könnte so aussehen:

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Wenn die Eigenschaftsreihenfolge in der Ausgabe für deine Anwendung wichtig ist, markiere alle Eigenschaften als erforderlich oder berücksichtige diese Neuordnung in deiner Parsing-Logik.



Ungültige Ausgaben

Obwohl strukturierte Ausgaben in den meisten Fällen Schema-Konformität garantieren, gibt es Szenarien, in denen die Ausgabe möglicherweise nicht deinem Schema entspricht:

Ablehnungen (stop_reason: "refusal")

Claude behält seine Sicherheits- und Hilfsbereitschaftseigenschaften auch bei der Verwendung strukturierter Ausgaben bei. Wenn Claude eine Anfrage aus Sicherheitsgründen ablehnt:

• Die Antwort hat stop_reason: "refusal"
• Du erhältst einen 200-Statuscode
• Dir werden die generierten Token in Rechnung gestellt
• Die Ausgabe entspricht möglicherweise nicht deinem Schema, da die Ablehnungsnachricht Vorrang vor Schema-Constraints hat

Token-Limit erreicht (stop_reason: "max_tokens")

Wenn die Antwort abgeschnitten wird, weil das max_tokens-Limit erreicht wurde:

• Die Antwort hat stop_reason: "max_tokens"
• Die Ausgabe kann unvollständig sein und nicht deinem Schema entsprechen
• Wiederhole die Anfrage mit einem höheren max_tokens-Wert, um die vollständige strukturierte Ausgabe zu erhalten

Groß-/Kleinschreibung von Enum-Werten

Strukturierte Ausgaben garantieren nicht die Groß-/Kleinschreibung von String-enum- und const-Werten: Claude kann einen Wert zurückgeben, der sich von deinem Schema nur in der Groß-/Kleinschreibung unterscheidet, typischerweise im ersten Buchstaben eines Wortes nach einem Leerzeichen. Zum Beispiel bei diesem Schema:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

Die Ausgabe kann "Conversation Topic 3" (großes „T") enthalten, obwohl dieser exakte Wert nicht im Enum enthalten ist. Die Antwort wird normal abgeschlossen, ohne Fehler und ohne speziellen stop_reason. Dies gilt sowohl für JSON-Ausgaben als auch für strikte Tool-Nutzung. Vergleiche Enum-Werte ohne Berücksichtigung der Groß-/Kleinschreibung und vermeide Enum-Werte, die sich nur in der Groß-/Kleinschreibung unterscheiden.



Schema-Komplexitätslimits

Strukturierte Ausgaben funktionieren, indem deine JSON-Schemas in eine Grammatik kompiliert werden, die Claudes Ausgabe einschränkt. Komplexere Schemas erzeugen größere Grammatiken, deren Kompilierung länger dauert. Zum Schutz vor übermäßigen Kompilierungszeiten erzwingt die API mehrere Komplexitätslimits.



Explizite Limits

Die folgenden Limits gelten für alle Anfragen mit output_config.format oder strict: true:



Zusätzliche interne Limits

Über die expliziten Limits in der vorstehenden Tabelle hinaus gibt es zusätzliche interne Limits für die Größe der kompilierten Grammatik. Diese Limits existieren, weil sich Schema-Komplexität nicht auf eine einzelne Dimension reduzieren lässt: Funktionen wie optionale Parameter, Union-Typen, verschachtelte Objekte und die Anzahl der Tools interagieren auf eine Weise miteinander, die die kompilierte Grammatik unverhältnismäßig groß machen kann.

Wenn diese Limits überschritten werden, erhältst du einen 400-Fehler mit der Meldung „Schema is too complex for compilation." Diese Fehler bedeuten, dass die kombinierte Komplexität deiner Schemas das überschreitet, was effizient kompiliert werden kann, selbst wenn jedes einzelne Limit in der vorstehenden Tabelle eingehalten wird. Als letzte Absicherung erzwingt die API außerdem ein Kompilierungs-Timeout von 180 Sekunden. Schemas, die alle expliziten Prüfungen bestehen, aber sehr große kompilierte Grammatiken erzeugen, können dieses Timeout erreichen.



Tipps zur Reduzierung der Schema-Komplexität

Wenn du an Komplexitätslimits stößt, probiere diese Strategien der Reihe nach aus:

1. Markiere nur kritische Tools als strikt. Wenn du viele Tools hast, reserviere es für Tools, bei denen Schema-Verletzungen echte Probleme verursachen, und verlasse dich bei einfacheren Tools auf Claudes natürliche Einhaltung.

2. Reduziere optionale Parameter. Mache Parameter wo möglich required. Jeder optionale Parameter verdoppelt ungefähr einen Teil des Zustandsraums der Grammatik. Wenn ein Parameter immer einen sinnvollen Standardwert hat, erwäge, ihn als erforderlich zu markieren und Claude diesen Standardwert explizit angeben zu lassen.

3. Vereinfache verschachtelte Strukturen. Tief verschachtelte Objekte mit optionalen Feldern verstärken die Komplexität. Flache Strukturen ab, wo möglich.

4. Teile in mehrere Anfragen auf. Wenn du viele strikte Tools hast, erwäge, sie auf separate Anfragen oder Sub-Agenten aufzuteilen.

Bei anhaltenden Problemen mit gültigen Schemas kontaktiere den Support mit deiner Schema-Definition.



Datenspeicherung

Prompts und Antworten werden bei der Verwendung strukturierter Ausgaben mit ZDR verarbeitet. Das JSON-Schema selbst wird jedoch zu Optimierungszwecken für bis zu 24 Stunden seit der letzten Verwendung temporär zwischengespeichert. Über die API-Antwort hinaus werden keine Prompt- oder Antwortdaten gespeichert.

Strukturierte Ausgaben sind HIPAA-geeignet, aber PHI darf nicht in JSON-Schema-Definitionen enthalten sein. Die API kompiliert JSON-Schemas in Grammatiken, die getrennt vom Nachrichteninhalt zwischengespeichert werden, und diese zwischengespeicherten Schemas erhalten nicht denselben PHI-Schutz wie Prompts und Antworten. Füge keine PHI in Schema-Eigenschaftsnamen, enum-Werte, const-Werte oder pattern-reguläre Ausdrücke ein. PHI sollte nur im Nachrichteninhalt (Prompts und Antworten) erscheinen, wo sie unter HIPAA-Schutzmaßnahmen geschützt ist.

Für ZDR- und HIPAA-Eignung über alle Funktionen hinweg siehe API und Datenspeicherung.



Funktionskompatibilität

Funktioniert mit:

• Batch-Verarbeitung: Verarbeite strukturierte Ausgaben in großem Maßstab mit 50 % Rabatt
• Token-Zählung: Zähle Token ohne Kompilierung
• Streaming: Streame strukturierte Ausgaben wie normale Antworten
• Kombinierte Nutzung: Verwende JSON-Ausgaben (output_config.format) und strikte Tool-Nutzung (strict: true) zusammen in derselben Anfrage

Inkompatibel mit:

• Zitationen: Zitationen erfordern das Einfügen von Zitationsblöcken zwischen Text, was mit strikten JSON-Schema-Constraints in Konflikt steht. Gibt einen 400-Fehler zurück, wenn Zitationen mit output_config.format aktiviert sind.
• Message Prefilling: Inkompatibel mit JSON-Ausgaben



Nächste Schritte