Strukturierte Ausgaben

Strukturierte Ausgaben beschränken Claudes Antworten auf ein bestimmtes Schema, um gültige, analysierbare Ausgaben für die nachgelagerte Verarbeitung zu gewährleisten. Verwenden Sie JSON-Ausgaben (output_format) für strukturierte Datenreaktionen oder striktes Tool-Einsatz (strict: true) für garantierte Schemavalidierung bei Tool-Namen und Eingaben.

Warum strukturierte Ausgaben verwenden

Ohne strukturierte Ausgaben kann Claude fehlerhafte JSON-Antworten oder ungültige Tool-Eingaben generieren, die Ihre Anwendungen unterbrechen. Selbst mit sorgfältiger Eingabeaufforderung können Sie auf folgende Probleme stoßen:

• Parsing-Fehler durch ungültige JSON-Syntax
• Fehlende erforderliche Felder
• Inkonsistente Datentypen
• Schemaverletzungen, die Fehlerbehandlung und Wiederholungen erfordern

Strukturierte Ausgaben garantieren schemakompatible Antworten durch eingeschränkte Dekodierung:

• Immer gültig: Keine JSON.parse()-Fehler mehr
• Typsicher: Garantierte Feldtypen und erforderliche Felder
• Zuverlässig: Keine Wiederholungen erforderlich für Schemaverletzungen
• Zwei Modi: JSON für Aufgaben wie Datenextraktion und strikte Tools für Situationen wie komplexe Tools und agentengesteuerte Workflows

Schnellstart

Wann JSON-Ausgaben vs. striktes Tool-Einsatz verwenden

Wählen Sie den richtigen Modus für Ihren Anwendungsfall:

Warum striktes Tool-Einsatz für Agenten wichtig ist

Der Aufbau zuverlässiger agentengesteuerter Systeme erfordert garantierte Schemakonformität. Ungültige Tool-Parameter unterbrechen Ihre Funktionen und Workflows. Claude könnte inkompatible Typen zurückgeben ("2" statt 2) oder Felder fehlen lassen, was zu Laufzeitfehlern führt.

Striktes Tool-Einsatz garantiert typsichere Parameter:

• Funktionen erhalten jedes Mal korrekt typisierte Argumente
• Keine Notwendigkeit, Tool-Aufrufe zu validieren und zu wiederholen
• Produktionsreife Agenten, die konsistent in großem Maßstab funktionieren

Angenommen, ein Buchungssystem benötigt passengers: int. Ohne strikten Modus könnte Claude passengers: "two" oder passengers: "2" bereitstellen. Mit strict: true ist garantiert passengers: 2.

Wie strukturierte Ausgaben funktionieren

Arbeiten mit JSON-Ausgaben in SDKs

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

Verwendung von Pydantic und Zod

Für Python- und TypeScript-Entwickler können Sie vertraute Schema-Definitionswerkzeuge wie Pydantic und Zod verwenden, anstatt rohe JSON-Schemas zu schreiben.

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

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

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    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

Python: client.beta.messages.parse() (Empfohlen)

Die parse()-Methode transformiert automatisch Ihr Pydantic-Modell, validiert die Antwort und gibt ein parsed_output-Attribut zurück.

Python: transform_schema()-Helfer

Für den Fall, dass Sie Schemas manuell transformieren müssen, bevor Sie sie senden, oder wenn Sie ein von Pydantic generiertes Schema ändern möchten. Im Gegensatz zu client.beta.messages.parse(), das bereitgestellte Schemas automatisch transformiert, erhalten Sie das transformierte Schema, damit Sie es weiter anpassen können.

Wie SDK-Transformation funktioniert

Sowohl Python- als auch TypeScript-SDKs transformieren automatisch Schemas mit nicht unterstützten Funktionen:

1. Entfernen Sie nicht unterstützte Einschränkungen (z. B. minimum, maximum, minLength, maxLength)
2. Aktualisieren Sie Beschreibungen mit Einschränkungsinformationen (z. B. "Muss mindestens 100 sein"), wenn die Einschränkung nicht direkt mit strukturierten Ausgaben unterstützt wird
3. Fügen Sie additionalProperties: false zu allen Objekten hinzu
4. Filtern Sie String-Formate auf unterstützte Liste nur
5. Validieren Sie Antworten gegen Ihr ursprüngliches Schema (mit allen Einschränkungen)

Dies bedeutet, dass Claude ein vereinfachtes Schema erhält, aber Ihr Code erzwingt immer noch alle Einschränkungen durch Validierung.

Beispiel: Ein Pydantic-Feld mit minimum: 100 wird zu einem einfachen Integer im gesendeten Schema, aber die Beschreibung wird auf "Muss mindestens 100 sein" aktualisiert, und das SDK validiert die Antwort gegen die ursprüngliche Einschränkung.

Häufige Anwendungsfälle

Wichtige Überlegungen

Grammatik-Kompilierung und Caching

Strukturierte Ausgaben verwenden eingeschränkte Sampling mit kompilierten Grammatik-Artefakten. Dies führt zu einigen Leistungsmerkmalen, die Sie beachten sollten:

• Erste Anfrage-Latenz: Das erste Mal, wenn Sie ein bestimmtes Schema verwenden, gibt es zusätzliche Latenz während die Grammatik kompiliert wird
• Automatisches Caching: Kompilierte Grammatiken werden 24 Stunden lang ab der letzten Verwendung zwischengespeichert, was nachfolgende Anfragen viel schneller macht
• Cache-Invalidierung: Der Cache wird invalidiert, wenn Sie ändern:
  • Die JSON-Schema-Struktur
  • Die Menge der Tools in Ihrer Anfrage (bei Verwendung von strukturierten Ausgaben und Tool-Einsatz)
  • Das Ändern nur von name- oder description-Feldern invalidiert den Cache nicht

Eingabeaufforderungsänderung und Token-Kosten

Bei Verwendung von strukturierten Ausgaben erhält Claude automatisch eine zusätzliche System-Eingabeaufforderung, die das erwartete Ausgabeformat erklärt. Dies bedeutet:

• Ihre Eingabe-Token-Anzahl wird leicht höher sein
• Die injizierte Eingabeaufforderung kostet Sie Token wie jede andere System-Eingabeaufforderung
• Das Ändern des output_format-Parameters invalidiert jedes Prompt-Caching für diesen Gesprächs-Thread

JSON-Schema-Einschränkungen

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

Ungültige Ausgaben

Während strukturierte Ausgaben in den meisten Fällen Schemakonformität garantieren, gibt es Szenarien, in denen die Ausgabe möglicherweise nicht Ihrem Schema entspricht:

Ablehnungen (stop_reason: "refusal")

Claude behält seine Sicherheits- und Hilfreichkeitseigenschaften auch bei Verwendung von strukturierten Ausgaben. Wenn Claude eine Anfrage aus Sicherheitsgründen ablehnt:

• Die Antwort hat stop_reason: "refusal"
• Sie erhalten einen 200-Statuscode
• Ihnen werden die generierten Token in Rechnung gestellt
• Die Ausgabe entspricht möglicherweise nicht Ihrem Schema (die Ablehnung hat Vorrang)

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 Ihrem Schema entsprechen
• Versuchen Sie es mit einem höheren max_tokens-Wert, um die vollständige strukturierte Ausgabe zu erhalten

Schema-Validierungsfehler

Wenn Ihr Schema nicht unterstützte Funktionen verwendet oder zu komplex ist, erhalten Sie einen 400-Fehler:

"Zu viele rekursive Definitionen im Schema"

• Ursache: Schema hat übermäßige oder zyklische rekursive Definitionen
• Lösung: Vereinfachen Sie die Schema-Struktur, reduzieren Sie die Verschachtelungstiefe

"Schema ist zu komplex"

• Ursache: Schema überschreitet Komplexitätsgrenzen
• Lösung: Teilen Sie in kleinere Schemas auf, vereinfachen Sie die Struktur oder reduzieren Sie die Anzahl der Tools, die als strict: true markiert sind

Bei anhaltenden Problemen mit gültigen Schemas kontaktieren Sie den Support mit Ihrer Schema-Definition.

Funktionskompatibilität

Funktioniert mit:

• Batch-Verarbeitung: Verarbeiten Sie strukturierte Ausgaben in großem Maßstab mit 50% Rabatt
• Token-Zählung: Zählen Sie Token ohne Kompilierung
• Streaming: Streamen Sie strukturierte Ausgaben wie normale Antworten
• Kombinierte Verwendung: Verwenden Sie JSON-Ausgaben (output_format) und striktes Tool-Einsatz (strict: true) zusammen in derselben Anfrage

Nicht kompatibel mit:

• Zitate: Zitate erfordern das Verschachteln von Zitat-Blöcken mit Text, was mit strikten JSON-Schema-Einschränkungen in Konflikt steht. Gibt 400-Fehler zurück, wenn Zitate mit output_format aktiviert sind.
• Nachrichtenvorab-Ausfüllung: Nicht kompatibel mit JSON-Ausgaben