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_config.format): Erhalten Sie Claudes Antwort in einem bestimmten JSON-Format
• Striktes Tool-Verwenden (strict: true): Garantieren Sie Schemavalidierung 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-Verstöße, die Fehlerbehandlung und Wiederholungen erfordern

Strukturierte Ausgaben garantieren schemakonform 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-Verstöße

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" \
  -d '{
    "model": "claude-opus-4-6",
    "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_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
        }
      }
    }
  }'

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
}

Wie es funktioniert

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.messages.create(
    model="claude-opus-4-6",
    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_config={
        "format": {
            "type": "json_schema",
            "schema": transform_schema(ContactInfo),
        }
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.messages.parse(
    model="claude-opus-4-6",
    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=ContactInfo,
)

print(response.parsed_output)

SDK-spezifische Methoden

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

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

Python: transform_schema()-Hilfsfunktion

Für Fälle, in denen 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.messages.parse(), das bereitgestellte Schemas automatisch transformiert, gibt dies Ihnen das transformierte Schema, damit Sie es weiter anpassen können.

Wie die SDK-Transformation funktioniert

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

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 die unterstützte Liste
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üssen
• Agentic-Workflows erstellen müssen
• Typsichere Funktionsaufrufe sicherstellen müssen
• Mit komplexen Tools mit verschachtelten Eigenschaften umgehen müssen

Warum striktes Tool-Verwenden für Agenten wichtig ist

Das Erstellen zuverlässiger Agentensysteme erfordert garantierte Schema-Konformität. Ohne strikten Modus könnte Claude inkompatible Typen zurückgeben ("2" statt 2) oder erforderliche Felder vermissen, 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 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 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" \
  -d '{
    "model": "claude-opus-4-6",
    "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)

Wie es funktioniert

Häufige Anwendungsfälle

Verwendung beider Funktionen zusammen

JSON-Ausgaben und striktes Tool-Verwenden lösen unterschiedliche 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.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Help me plan a trip to Paris for next month"}],
    # JSON outputs: structured response format
    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
            }
        }
    },
    # 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 Stichproben 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

Eingabeaufforderungsänderung und Token-Kosten

Bei Verwendung von strukturierten Ausgaben erhält Claude automatisch eine zusätzliche Systemeingabeaufforderung, 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 Systemeingabeaufforderung
• Das Ändern des Parameters output_config.format 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

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
• 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_config.format) und striktes Tool-Verwenden (strict: true) zusammen in derselben Anfrage

Nicht kompatibel mit:

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