Strukturierte Ausgaben

Strukturierte Ausgaben schränken Claudes Antworten ein, um einem bestimmten Schema zu folgen, und gewährleisten so gültige, parsierbare Ausgaben für die nachgelagerte Verarbeitung. Zwei ergänzende Funktionen sind verfügbar:

• JSON-Ausgaben (output_config.format): Claudes Antwort in einem bestimmten JSON-Format erhalten
• Striktes Tool-Verwenden (strict: true): Schema-Validierung für Tool-Namen und -Eingaben garantieren

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 zum Absturz bringen. Selbst mit sorgfältigem Prompting können folgende Probleme auftreten:

• Parse-Fehler durch ungültige JSON-Syntax
• Fehlende Pflichtfelder
• Inkonsistente Datentypen
• Schema-Verletzungen, die Fehlerbehandlung und Wiederholungsversuche erfordern

Strukturierte Ausgaben garantieren schema-konforme Antworten durch eingeschränktes Decoding:

• Immer gültig: Keine JSON.parse()-Fehler mehr
• Typsicher: Garantierte Feldtypen und Pflichtfelder
• Zuverlässig: Keine Wiederholungsversuche bei Schema-Verletzungen erforderlich

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 Folgendes benötigen:

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

Schnellstart

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

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

So funktioniert es

Arbeiten mit JSON-Ausgaben in SDKs

Die SDKs bieten Hilfsmethoden, die die Arbeit mit JSON-Ausgaben erleichtern, einschließlich Schema-Transformation, automatischer Validierung und Integration mit gängigen Schema-Bibliotheken.

Verwendung nativer Schema-Definitionen

Anstatt rohe JSON-Schemas zu schreiben, können Sie vertraute Schema-Definitionswerkzeuge in Ihrer Sprache verwenden:

• Python: Pydantic-Modelle mit client.messages.parse()
• TypeScript: Zod-Schemas mit zodOutputFormat()
• Java: Einfache Java-Klassen mit automatischer Schema-Ableitung über outputFormat(Class<T>)
• Ruby: Anthropic::BaseModel-Klassen mit output_config: {format: Model}
• C#, Go, PHP: Rohe JSON-Schemas über output_config

SDK-spezifische Methoden

Jedes SDK bietet Hilfsmethoden, die die Arbeit mit strukturierten Ausgaben erleichtern. Vollständige Details finden Sie auf den einzelnen SDK-Seiten.

Wie die SDK-Transformation funktioniert

Die Python- und TypeScript-SDKs transformieren Schemas mit nicht unterstützten Funktionen automatisch:

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

Das bedeutet, dass Claude ein vereinfachtes Schema erhält, aber Ihr Code alle Einschränkungen durch Validierung weiterhin durchsetzt.

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

Strikter Tool-Einsatz

Der strikte Tool-Einsatz validiert Tool-Parameter und stellt sicher, dass Claude Ihre Funktionen mit korrekt typisierten Argumenten aufruft. Verwenden Sie den strikten Tool-Einsatz, wenn Sie Folgendes benötigen:

• Tool-Parameter validieren
• Agentische Workflows aufbauen
• Typsichere Funktionsaufrufe sicherstellen
• Komplexe Tools mit verschachtelten Eigenschaften handhaben

Warum strikter Tool-Einsatz für Agenten wichtig ist

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

Strikter 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 im großen Maßstab funktionieren

Angenommen, ein Buchungssystem benötigt passengers: int. Ohne strikten Modus könnte Claude passengers: "two" oder passengers: "2" liefern. Mit strict: true enthält die Antwort immer passengers: 2.

Schnellstart

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 strikt dem input_schema
• Tool-name ist immer gültig (aus bereitgestellten Tools oder Server-Tools)

Wie es funktioniert

Häufige Anwendungsfälle

Beide Funktionen zusammen verwenden

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

• JSON-Ausgaben steuern das Antwortformat von Claude (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 agentische Workflows, bei denen Sie sowohl zuverlässige Tool-Aufrufe als auch strukturierte Endausgaben benötigen.

Wichtige Überlegungen

Grammatik-Kompilierung und Caching

Strukturierte Ausgaben verwenden eingeschränktes Sampling mit kompilierten Grammatik-Artefakten. Dies bringt einige Leistungsmerkmale mit sich, die zu beachten sind:

• Latenz bei der ersten Anfrage: Wenn Sie ein bestimmtes Schema zum ersten Mal verwenden, entsteht zusätzliche Latenz, während die Grammatik kompiliert wird
• Automatisches Caching: Kompilierte Grammatiken werden 24 Stunden ab der letzten Verwendung gecacht, wodurch nachfolgende Anfragen deutlich schneller werden
• Cache-Invalidierung: Der Cache wird invalidiert, wenn Sie Folgendes ändern:
  • Die JSON-Schema-Struktur
  • Die Menge der Tools in Ihrer Anfrage (wenn Sie sowohl strukturierte Ausgaben als auch Tool-Verwenden nutzen)
  • 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, der das erwartete Ausgabeformat erklärt. Das bedeutet:

• Ihre Eingabe-Token-Anzahl wird etwas höher sein
• Der eingefügte Prompt kostet Sie Token wie jeder andere System-Prompt
• Das Ändern des Parameters output_config.format invalidiert jeden Prompt-Cache für diesen Konversations-Thread

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.

Eigenschaftsreihenfolge

Bei der Verwendung strukturierter Ausgaben behalten Eigenschaften in Objekten ihre definierte Reihenfolge aus Ihrem Schema bei, mit einem wichtigen Vorbehalt: Erforderliche Eigenschaften erscheinen zuerst, gefolgt von optionalen Eigenschaften.

Zum Beispiel, gegeben dieses Schema:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Die Ausgabe wird Eigenschaften in folgender Reihenfolge anordnen:

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 wie folgt aussehen:

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Wenn die Eigenschaftsreihenfolge in der Ausgabe für Ihre Anwendung wichtig ist, stellen Sie sicher, dass alle Eigenschaften als erforderlich markiert sind, oder berücksichtigen Sie diese Neuanordnung in Ihrer 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 mit Ihrem Schema übereinstimmt:

Ablehnungen (stop_reason: "refusal")

Claude behält seine Sicherheits- und Hilfseigenschaften auch bei der Verwendung strukturierter Ausgaben bei. 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 stimmt möglicherweise nicht mit Ihrem Schema überein, da die Ablehnungsnachricht 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 mit Ihrem Schema übereinstimmen
• Wiederholen Sie die Anfrage mit einem höheren max_tokens-Wert, um die vollständige strukturierte Ausgabe zu erhalten

Schema-Komplexitätsgrenzen

Strukturierte Ausgaben funktionieren, indem Ihre JSON-Schemas in eine Grammatik kompiliert werden, die Claudes Ausgabe einschränkt. Komplexere Schemas erzeugen größere Grammatiken, die länger zum Kompilieren brauchen. Um übermäßige Kompilierungszeiten zu verhindern, 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 hinaus gibt es zusätzliche interne Grenzen für die kompilierte Grammatikgröße. 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 miteinander auf eine Weise, die die kompilierte Grammatik unverhältnismäßig groß machen kann.

Wenn diese Grenzen überschritten werden, erhalten Sie einen 400-Fehler mit der Meldung "Schema is too complex for compilation." Diese Fehler bedeuten, dass die kombinierte Komplexität Ihrer Schemas das überschreitet, was effizient kompiliert werden kann, auch wenn jede einzelne Grenze oben eingehalten wird. Als letztes Sicherheitsnetz setzt die API auch 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 Sie auf Komplexitätsgrenzen stoßen, versuchen Sie diese Strategien der Reihe nach:

1. Markieren Sie nur kritische Tools als strikt. Wenn Sie viele Tools haben, reservieren Sie es für Tools, bei denen Schema-Verletzungen echte Probleme verursachen, und verlassen Sie sich auf Claudes natürliche Einhaltung für einfachere Tools.

2. Reduzieren Sie optionale Parameter. Machen Sie Parameter wo möglich required. Jeder optionale Parameter verdoppelt ungefähr einen Teil des Zustandsraums der Grammatik. Wenn ein Parameter immer einen vernünftigen Standardwert hat, erwägen Sie, ihn erforderlich zu machen und Claude diesen Standard explizit angeben zu lassen.

3. Vereinfachen Sie verschachtelte Strukturen. Tief verschachtelte Objekte mit optionalen Feldern erhöhen die Komplexität. Flachen Sie Strukturen wo möglich ab.

4. Aufteilen in mehrere Anfragen. Wenn Sie viele strikte Tools haben, erwägen Sie, diese auf separate Anfragen oder Unteragenten aufzuteilen.

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

Datenspeicherung

Prompts und Antworten werden mit ZDR verarbeitet, wenn strukturierte Ausgaben verwendet werden. Das JSON-Schema selbst wird jedoch zu Optimierungszwecken vorübergehend bis zu 24 Stunden seit der letzten Verwendung gecacht. Es werden keine Prompt- oder Antwortdaten über die API-Antwort hinaus gespeichert.

Informationen zur ZDR-Berechtigung für alle Funktionen finden Sie unter API und Datenspeicherung.

Funktionskompatibilität

Funktioniert mit:

• Batch-Verarbeitung: Strukturierte Ausgaben im großen Maßstab mit 50% Rabatt verarbeiten
• Token-Zählung: Token ohne Kompilierung zählen
• Streaming: Strukturierte Ausgaben wie normale Antworten streamen
• Kombinierte Nutzung: JSON-Ausgaben (output_config.format) und striktes Tool-Verwenden (strict: true) zusammen in derselben Anfrage verwenden

Inkompatibel mit:

• Zitierungen: Zitierungen erfordern das Einstreuen von Zitierblöcken in Text, was mit strikten JSON-Schema-Einschränkungen in Konflikt steht. Gibt einen 400-Fehler zurück, wenn Zitierungen mit output_config.format aktiviert sind.
• Nachrichten-Prefilling: Inkompatibel mit JSON-Ausgaben