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
• Strikte Tool-Nutzung (strict: true): Garantiere Schema-Validierung für Tool-Namen und -Eingaben

Du kannst diese Funktionen unabhängig voneinander oder gemeinsam 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

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-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,
            },
        }
    },
)
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": "john@example.com",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

So funktioniert es

1. 1

   Definiere dein JSON-Schema

   Erstelle ein JSON-Schema, das die Struktur beschreibt, der Claude folgen soll. Das Schema verwendet das Standard-JSON-Schema-Format mit einigen Einschränkungen (siehe JSON-Schema-Einschränkungen).

2. 2

   Füge den Parameter output_config.format hinzu

   Füge den Parameter output_config.format mit type: "json_schema" und deiner Schema-Definition in deine API-Anfrage ein.

3. 3

   Parse die Antwort

   Claudes Antwort ist gültiges JSON, das deinem Schema entspricht, und wird im Text-Content-Block der Antwort zurückgegeben.

Arbeiten mit JSON-Ausgaben in SDKs

Die SDKs bieten Hilfsfunktionen, die das Arbeiten mit JSON-Ausgaben erleichtern, darunter Schema-Transformation, automatische Validierung und Integration mit gängigen Schema-Bibliotheken.

Native Schema-Definitionen verwenden

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-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)

SDK-spezifische Methoden

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

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, 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 und transformiere es dann
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-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 „Must be at least 100“), wenn der Constraint nicht direkt von strukturierten Ausgaben unterstützt wird
3. additionalProperties: false hinzufügen zu allen Objekten
4. String-Formate filtern auf die Liste der unterstützten Formate
5. Antworten validieren gegen dein ursprüngliches Schema (mit allen Constraints)

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

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

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 gemeinsam 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

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.

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 Nutzung: Verwende JSON-Ausgaben (output_config.format) und strikte Tool-Nutzung (strict: true) gemeinsam 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