Strukturierte Ausgaben

„Structured outputs" (strukturierte Ausgaben) beschränken Claudes Antworten darauf, einem bestimmten Schema zu folgen, und gewährleisten so eine gültige, parsbare Ausgabe für die nachgelagerte Verarbeitung. 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 bei sorgfältigem Prompting kannst du auf Folgendes stoßen:

• 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 Decoding):

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



JSON-Ausgaben

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

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



Schnellstart

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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(next(block.text for block in response.content if block.type == "text"))

Antwortformat: Gültiges JSON, das deinem Schema entspricht, im Text-Content-Block der Antwort

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



So funktioniert es



Arbeiten mit JSON-Ausgaben in SDKs

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



Native Schema-Definitionen verwenden

Anstatt rohe JSON-Schemas zu schreiben, kannst du vertraute Schema-Definitions-Tools 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-5",
    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 Hilfsfunktionen, die die Arbeit mit strukturierten Ausgaben erleichtern. Vollständige Details findest du auf den einzelnen SDK-Seiten.

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, [email protected], interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Greife direkt auf die geparste Ausgabe zu
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# Konvertiere zuerst das Pydantic-Modell in ein JSON-Schema, dann transformiere es
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# Passe das Schema bei Bedarf an
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)



So funktioniert die SDK-Transformation

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-Reflection oder BetaJSONSchemaOutputFormat() auf der Go-Beta-API). Die Transformationsschritte:

1. Nicht unterstützte Constraints entfernen (zum Beispiel minimum, maximum, minLength, maxLength)
2. Beschreibungen aktualisieren mit Constraint-Informationen (zum Beispiel „Muss mindestens 100 sein"), wenn der Constraint nicht direkt mit strukturierten Ausgaben unterstützt wird
3. additionalProperties: false hinzufügen zu allen Objekten
4. String-Formate filtern auf die unterstützte Liste
5. Antworten validieren 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 „Muss mindestens 100 sein" und validiert die Antwort gegen den ursprünglichen Constraint.



Häufige Anwendungsfälle



Strikte Tool-Nutzung

Zum Erzwingen 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 arbeiten 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. Dies ist nützlich für agentische Workflows, bei denen du sowohl zuverlässige Tool-Aufrufe als auch strukturierte Endausgaben benötigst.

response = client.messages.create(
    model="claude-opus-5",
    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 Performance-Eigenschaften mit sich, die du beachten solltest:

• Latenz bei der ersten Anfrage: Beim ersten Verwenden eines bestimmten Schemas gibt es zusätzliche Latenz, während die Grammatik kompiliert wird
• Automatisches Caching: Kompilierte Grammatiken werden 24 Stunden ab der letzten Verwendung gecacht, wodurch nachfolgende Anfragen viel schneller sind
• Cache-Invalidierung: Der Cache wird invalidiert, wenn du Folgendes änderst:
  • Die JSON-Schema-Struktur
  • Die Menge der Tools in deiner Anfrage (bei gleichzeitiger 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 Input-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.



Property-Reihenfolge

Bei der Verwendung strukturierter Ausgaben behalten Properties in Objekten ihre definierte Reihenfolge aus deinem Schema bei, mit einer wichtigen Einschränkung: Erforderliche Properties erscheinen zuerst, gefolgt von optionalen Properties.

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 Properties 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 Property-Reihenfolge in der Ausgabe für deine Anwendung wichtig ist, markiere alle Properties als erforderlich oder berücksichtige diese Neuordnung in deiner Parsing-Logik.



Ungültige Ausgaben

Während 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 aufgrund des Erreichens des max_tokens-Limits abgeschnitten wird:

• 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 beim 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 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 einzige Dimension reduzieren lässt: Funktionen wie optionale Parameter, Union-Typen, verschachtelte Objekte und Anzahl der Tools interagieren miteinander auf Weisen, die die kompilierte Grammatik unverhältnismäßig groß machen können.

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 übersteigt, was effizient kompiliert werden kann, selbst wenn jedes einzelne Limit in der vorstehenden Tabelle erfüllt ist. 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 auf 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 erforderlich zu machen 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 bis zu 24 Stunden seit der letzten Verwendung temporär gecacht. Keine Prompt- oder Antwortdaten werden über die API-Antwort hinaus gespeichert.

Strukturierte Ausgaben sind HIPAA-fähig, aber PHI dürfen nicht in JSON-Schema-Definitionen enthalten sein. Die API kompiliert JSON-Schemas in Grammatiken, die separat vom Nachrichteninhalt gecacht werden, und diese gecachten Schemas erhalten nicht denselben PHI-Schutz wie Prompts und Antworten. Füge keine PHI in Schema-Property-Namen, enum-Werte, const-Werte oder pattern-Reguläre-Ausdrücke ein. PHI sollten nur im Nachrichteninhalt (Prompts und Antworten) erscheinen, wo sie unter HIPAA-Schutzmaßnahmen geschützt sind.

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



Funktionskompatibilität

Funktioniert mit:

• Batch-Verarbeitung: Verarbeite strukturierte Ausgaben im großen 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:

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



Nächste Schritte