Strukturierte Ausgaben

„Structured outputs“ (strukturierte Ausgaben) 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, zum Beispiel um Daten aus Bildern oder Text zu extrahieren, strukturierte Berichte zu erstellen oder API-Antworten zu formatieren. Diese Seite behandelt JSON-Ausgaben.
• „Strict tool use“ (strikte Tool-Nutzung) (strict: true): Garantiere die Schema-Validierung von Tool-Namen und -Eingaben. Siehe Strikte Tool-Nutzung.

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änkte Dekodierung):

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

Funktionsweise

1. 1

   Definiere dein Schema

   Beschreibe die gewünschte Struktur als JSON-Schema oder als Typ in deiner Sprache. Das Schema folgt JSON Schema, mit einigen Einschränkungen.

2. 2

   Sende es in output_config.format

   Die Anfrage enthält das Schema in output_config.format mit type: "json_schema". SDK-Helfer setzen dies für dich.

3. 3

   Lies die Antwort

   Claude gibt gültiges JSON, das deinem Schema entspricht, im Text-Content-Block der Antwort zurück. SDK-Helfer parsen es in deinen Typ.

Verwendung

from pydantic import BaseModel
# ...


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


client = Anthropic()

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

print(response.parsed_output)

name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

Wie die SDK-Transformation funktioniert

Die meisten SDK-Helfer transformieren Schemas, die nicht unterstützte Funktionen verwenden. Die Transformationsschritte:

1. Nicht unterstützte Constraints entfernen (zum Beispiel minimum, maximum, minLength, maxLength)
2. Beschreibungen aktualisieren, indem jeder nicht unterstützte Constraint zur Beschreibung des Feldes hinzugefügt wird (zum Beispiel {minimum: 100})
3. additionalProperties: false hinzufügen zu allen Objekten
4. String-Formate filtern, sodass nur die unterstützte Liste übrig bleibt
5. Antworten validieren gegen dein ursprüngliches Schema und alle seine Constraints, sofern der Helfer Antworten validiert

Claude erhält ein vereinfachtes Schema, aber ein Helfer, der Antworten validiert, setzt in deinem Code weiterhin jeden Constraint durch.

Beispiel: Ein Feld mit minimum: 100 wird im gesendeten Schema zu einem einfachen Integer, und das SDK fügt {minimum: 100} zur Beschreibung des Feldes hinzu. Ein Helfer, der Antworten validiert, prüft die Antwort weiterhin gegen minimum: 100.

Ein rohes JSON-Schema verwenden

Um ein JSON-Schema aus einer Datei, einer OpenAPI-Spezifikation oder aus Code zu verwenden, der es zur Laufzeit erstellt, übergib es in output_config.format.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) 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,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

Häufige Anwendungsfälle

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

Strikte Tool-Nutzung

Um die JSON-Schema-Konformität von Tool-Eingaben mit grammatikbeschränktem Sampling durchzusetzen, 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. Das 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-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. Das bringt einige Leistungsmerkmale mit sich, die du kennen solltest:

• Latenz der ersten Anfrage: Wenn du ein bestimmtes Schema zum ersten Mal verwendest, entsteht zusätzliche „latency“ (Latenz), während die Grammatik kompiliert wird
• Automatisches Caching: Kompilierte Grammatiken werden ab der letzten Verwendung 24 Stunden lang gecacht, 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 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“ (System-Prompt), der das erwartete Ausgabeformat erklärt. Das bedeutet:

• Deine Anzahl an Eingabe-Token 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 Konversationsstrang

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.

Reihenfolge der Properties

Bei der Verwendung strukturierter Ausgaben behalten Properties in Objekten ihre in deinem Schema definierte Reihenfolge 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 die 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": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Wenn die Reihenfolge der Properties in der Ausgabe für deine Anwendung wichtig ist, markiere alle Properties als erforderlich oder berücksichtige diese Umordnung 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

Eine Property, die nach dem Nachdenken des Modells oder nach schrittweisem Reasoning fragt, kann zu einer reasoning_extraction-Ablehnung führen. Frage stattdessen nach einer kurzen Erklärung. Siehe Reasoning in Thinking-Blöcken belassen.

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 ist möglicherweise unvollständig und entspricht nicht deinem Schema
• 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 steht. Die Antwort wird normal abgeschlossen, ohne Fehler und ohne speziellen stop_reason. Das 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.

Grenzen der Schema-Komplexität

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 setzt die API mehrere Komplexitätsgrenzen durch.

Explizite Grenzen

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

Zusätzliche interne Grenzen

Über die expliziten Grenzen in der vorstehenden Tabelle hinaus gibt es zusätzliche interne Grenzen für die Größe der kompilierten Grammatik. Diese Grenzen existieren, weil sich Schema-Komplexität nicht auf eine einzige 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 Grenzen ü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 jede einzelne Grenze in der vorstehenden Tabelle eingehalten wird. Als letzte Absicherung setzt die API außerdem ein Kompilierungs-Timeout von 180 Sekunden durch. 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ätsgrenzen stößt, probiere diese Strategien in dieser Reihenfolge:

1. Markiere nur kritische Tools als strikt. Wenn du viele Tools hast, reserviere dies 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 potenzieren die Komplexität. Flache Strukturen wo möglich ab.

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.

Migration von der Beta

Der Parameter output_format wurde nach output_config.format verschoben, und Beta-Header sind nicht mehr erforderlich. Der Parameter output_format ist abgekündigt und wird in Zukunft entfernt. Um ihn dennoch zu verwenden, füge den Beta-Header structured-outputs-2025-11-13 hinzu. Ohne ihn gibt die API einen 400-Fehler zurück.

Das Python-SDK (v1.0 und höher) akzeptiert output_format={...} bei client.beta.messages.create() oder count_tokens() nicht und löst einen TypeError aus. Verwende stattdessen output_config. Siehe Ein rohes JSON-Schema verwenden für die aktualisierte API-Form.

Datenaufbewahrung

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

Strukturierte Ausgaben sind HIPAA-fähig, aber PHI darf nicht in JSON-Schema-Definitionen enthalten sein. Die API kompiliert JSON-Schemas in Grammatiken, die getrennt 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 reguläre Ausdrücke in pattern ein. PHI sollte nur im Nachrichteninhalt (Prompts und Antworten) erscheinen, wo es durch HIPAA-Schutzmaßnahmen geschützt ist.

Zur ZDR- und HIPAA-Fähigkeit über alle Funktionen hinweg siehe API und Datenaufbewahrung.

Funktionskompatibilität

Funktioniert mit:

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

Inkompatibel mit:

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

Nächste Schritte

Compatibility