Strukturierte Ausgaben

Strukturierte Ausgaben beschränken Claudes Antworten auf ein bestimmtes Schema und stellen sicher, dass die Ausgabe gültig und analysierbar ist. Verwenden Sie JSON-Ausgaben (output_format) für strukturierte Datenreaktionen oder striktes Tool-Verwenden (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ältigem Prompting 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-Verwenden verwenden

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

Warum striktes Tool-Verwenden 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-Verwenden 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.

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 hier das transformierte Schema, damit Sie es weiter anpassen können.

Wie SDK-Transformation funktioniert

Beide Python- und TypeScript-SDKs transformieren Schemas automatisch 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 weiterhin 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 Stichproben mit kompilierten Grammatik-Artefakten. Dies führt zu einigen Leistungsmerkmalen, die Sie beachten sollten:

• Erste Anfrage-Latenz: Wenn Sie ein bestimmtes Schema zum ersten Mal verwenden, gibt es zusätzliche Latenz während die Grammatik kompiliert wird
• Automatisches Caching: Kompilierte Grammatiken werden 24 Stunden nach letzter 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-Verwenden)
  • Das Ändern nur von name- oder description-Feldern invalidiert den Cache nicht

Prompt-Änderung und Token-Kosten

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

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

JSON-Schema-Einschränkungen

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

Ungültige Ausgaben

Obwohl 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 erneut, 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-Verwenden (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.
• Message Prefilling: Nicht kompatibel mit JSON-Ausgaben

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)