Strukturierte Ausgaben

Strukturierte Ausgaben beschränken Claudes Antworten auf ein bestimmtes Schema und stellen sicher, dass die Ausgabe gültig und analysierbar ist. Zwei komplementäre Funktionen sind verfügbar:

• JSON-Ausgaben (output_format): Erhalten Sie Claudes Antwort in einem bestimmten JSON-Format
• Striktes Tool-Verwenden (strict: true): Garantieren Sie Schema-Validierung bei Tool-Namen und Eingaben

Diese Funktionen können unabhängig voneinander oder zusammen in derselben Anfrage verwendet werden.

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
• Schema-Verletzungen, die Fehlerbehandlung und Wiederholungen erfordern

Strukturierte Ausgaben garantieren Schema-konforme 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 Schema-Verletzungen

JSON-Ausgaben

JSON-Ausgaben steuern Claudes Antwortformat und stellen sicher, dass Claude gültiges JSON zurückgibt, das Ihrem Schema entspricht. Verwenden Sie JSON-Ausgaben, wenn Sie:

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

Schnellstart

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: structured-outputs-2025-11-13" \
  -d '{
    "model": "claude-sonnet-4-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": {
      "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
      }
    }
  }'

Antwortformat: Gültiges JSON, das Ihrem Schema in response.content[0].text entspricht

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

Funktionsweise

Arbeiten mit JSON-Ausgaben in SDKs

Die Python- und TypeScript-SDKs bieten Hilfsfunktionen, 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()-Hilfsfunktion

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.

Funktionsweise der SDK-Transformation

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 immer noch alle Einschränkungen durch Validierung.

Beispiel: Ein Pydantic-Feld mit minimum: 100 wird zu einer einfachen Ganzzahl 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

Striktes Tool-Verwenden

Striktes Tool-Verwenden validiert Tool-Parameter und stellt sicher, dass Claude Ihre Funktionen mit korrekt typisierten Argumenten aufruft. Verwenden Sie striktes Tool-Verwenden, wenn Sie:

• Tool-Parameter validieren möchten
• Agentic-Workflows erstellen möchten
• Typsichere Funktionsaufrufe sicherstellen möchten
• Komplexe Tools mit verschachtelten Eigenschaften handhaben möchten

Warum striktes Tool-Verwenden für Agenten wichtig ist

Der Aufbau zuverlässiger Agentensysteme erfordert garantierte Schema-Konformität. Ohne strikten Modus könnte Claude inkompatible Typen ("2" statt 2) oder fehlende erforderliche Felder zurückgeben, was Ihre Funktionen unterbricht und Laufzeitfehler verursacht.

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 im großen 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 enthält die Antwort immer passengers: 2.

Schnellstart

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: structured-outputs-2025-11-13" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }]
  }'

Antwortformat: Tool-Use-Blöcke mit validierten Eingaben in response.content[x].input

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Garantien:

• Tool input folgt streng dem input_schema
• Tool name ist immer gültig (von bereitgestellten Tools oder Server-Tools)

Funktionsweise

Häufige Anwendungsfälle

Verwendung beider Funktionen zusammen

JSON-Ausgaben und striktes Tool-Verwenden lösen verschiedene Probleme und können zusammen verwendet werden:

• JSON-Ausgaben steuern Claudes Antwortformat (was Claude sagt)
• Striktes Tool-Verwenden validiert Tool-Parameter (wie Claude Ihre 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 Agentic-Workflows, bei denen Sie sowohl zuverlässige Tool-Aufrufe als auch strukturierte endgültige Ausgaben benötigen.

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "Help me plan a trip to Paris for next month"}],
    # JSON outputs: structured response format
    output_format={
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"},
                "next_steps": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["summary", "next_steps"],
            "additionalProperties": False
        }
    },
    # Strict tool use: guaranteed tool parameters
    tools=[{
        "name": "search_flights",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "destination": {"type": "string"},
                "date": {"type": "string", "format": "date"}
            },
            "required": ["destination", "date"],
            "additionalProperties": False
        }
    }]
)

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-Verwenden zusammen)
  • 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 Input-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-Cache 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

Während strukturierte Ausgaben in den meisten Fällen Schema-Konformitä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
• Sie werden für die generierten Token abgerechnet
• Die Ausgabe entspricht möglicherweise nicht Ihrem Schema, da die Ablehnungsmeldung Vorrang vor Schema-Einschränkungen 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 Ihrem Schema entsprechen
• Wiederholen Sie 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 im großen 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:

• Zitationen: Zitationen erfordern das Verflechten von Zitationsblöcken mit Text, was mit strikten JSON-Schema-Einschränkungen in Konflikt steht. Gibt 400-Fehler zurück, wenn Zitationen mit output_format aktiviert sind.
• Message Prefilling: Nicht kompatibel mit JSON-Ausgaben