Sorties structurées

Les sorties structurées contraignent les réponses de Claude à suivre un schéma spécifique, garantissant une sortie valide et analysable pour le traitement en aval. Utilisez les sorties JSON (output_format) pour les réponses de données structurées, ou l'utilisation stricte d'outils (strict: true) pour la validation de schéma garantie sur les noms et entrées d'outils.

Pourquoi utiliser les sorties structurées

Sans sorties structurées, Claude peut générer des réponses JSON mal formées ou des entrées d'outils invalides qui cassent vos applications. Même avec un invite soigné, vous pouvez rencontrer :

• Des erreurs d'analyse dues à une syntaxe JSON invalide
• Des champs obligatoires manquants
• Des types de données incohérents
• Des violations de schéma nécessitant une gestion des erreurs et des tentatives

Les sorties structurées garantissent des réponses conformes au schéma grâce au décodage contraint :

• Toujours valide : Plus d'erreurs JSON.parse()
• Type-safe : Types de champs garantis et champs obligatoires
• Fiable : Aucune tentative nécessaire pour les violations de schéma
• Deux modes : JSON pour des tâches comme l'extraction de données, et outils stricts pour des situations comme les outils complexes et les flux de travail agentiques

Démarrage rapide

Quand utiliser les sorties JSON par rapport à l'utilisation stricte d'outils

Choisissez le bon mode pour votre cas d'usage :

Pourquoi l'utilisation stricte d'outils est importante pour les agents

La construction de systèmes agentiques fiables nécessite une conformité de schéma garantie. Les paramètres d'outils invalides cassent vos fonctions et flux de travail. Claude pourrait retourner des types incompatibles ("2" au lieu de 2) ou des champs manquants, causant des erreurs d'exécution.

L'utilisation stricte d'outils garantit des paramètres type-safe :

• Les fonctions reçoivent des arguments correctement typés à chaque fois
• Aucun besoin de valider et réessayer les appels d'outils
• Les agents prêts pour la production qui fonctionnent de manière cohérente à grande échelle

Par exemple, supposons qu'un système de réservation ait besoin de passengers: int. Sans le mode strict, Claude pourrait fournir passengers: "two" ou passengers: "2". Avec strict: true, vous êtes garanti passengers: 2.

Comment fonctionnent les sorties structurées

Travailler avec les sorties JSON dans les SDK

Les SDK Python et TypeScript fournissent des assistants qui facilitent le travail avec les sorties JSON, y compris la transformation de schéma, la validation automatique et l'intégration avec les bibliothèques de schéma populaires.

Utilisation de Pydantic et Zod

Pour les développeurs Python et TypeScript, vous pouvez utiliser des outils de définition de schéma familiers comme Pydantic et Zod au lieu d'écrire des schémas JSON bruts.

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)

Méthodes spécifiques aux SDK

Python : client.beta.messages.parse() (Recommandé)

La méthode parse() transforme automatiquement votre modèle Pydantic, valide la réponse et retourne un attribut parsed_output.

Python : Assistant transform_schema()

Pour quand vous avez besoin de transformer manuellement les schémas avant d'envoyer, ou quand vous voulez modifier un schéma généré par Pydantic. Contrairement à client.beta.messages.parse(), qui transforme les schémas fournis automatiquement, cela vous donne le schéma transformé pour que vous puissiez le personnaliser davantage.

Comment fonctionne la transformation SDK

Les SDK Python et TypeScript transforment automatiquement les schémas avec des fonctionnalités non supportées :

1. Supprimez les contraintes non supportées (par exemple, minimum, maximum, minLength, maxLength)
2. Mettez à jour les descriptions avec les informations de contrainte (par exemple, « Doit être au moins 100 »), quand la contrainte n'est pas directement supportée avec les sorties structurées
3. Ajoutez additionalProperties: false à tous les objets
4. Filtrez les formats de chaîne à la liste supportée uniquement
5. Validez les réponses par rapport à votre schéma d'origine (avec toutes les contraintes)

Cela signifie que Claude reçoit un schéma simplifié, mais votre code applique toujours toutes les contraintes grâce à la validation.

Exemple : Un champ Pydantic avec minimum: 100 devient un entier simple dans le schéma envoyé, mais la description est mise à jour en « Doit être au moins 100 », et le SDK valide la réponse par rapport à la contrainte d'origine.

Cas d'usage courants

Considérations importantes

Compilation de grammaire et mise en cache

Les sorties structurées utilisent l'échantillonnage contraint avec des artefacts de grammaire compilés. Cela introduit certaines caractéristiques de performance à connaître :

• Latence de première requête : La première fois que vous utilisez un schéma spécifique, il y aura une latence supplémentaire pendant que la grammaire est compilée
• Mise en cache automatique : Les grammaires compilées sont mises en cache pendant 24 heures à partir de la dernière utilisation, rendant les requêtes suivantes beaucoup plus rapides
• Invalidation du cache : Le cache est invalidé si vous modifiez :
  • La structure du schéma JSON
  • L'ensemble des outils dans votre requête (lors de l'utilisation à la fois des sorties structurées et de l'utilisation d'outils)
  • La modification uniquement des champs name ou description n'invalide pas le cache

Modification d'invite et coûts en tokens

Lors de l'utilisation des sorties structurées, Claude reçoit automatiquement une invite système supplémentaire expliquant le format de sortie attendu. Cela signifie :

• Votre nombre de tokens d'entrée sera légèrement plus élevé
• L'invite injectée vous coûte des tokens comme toute autre invite système
• La modification du paramètre output_format invalidera tout prompt cache pour ce fil de conversation

Limitations du schéma JSON

Les sorties structurées supportent le schéma JSON standard avec certaines limitations. Les sorties JSON et l'utilisation stricte d'outils partagent ces limitations.

Sorties invalides

Bien que les sorties structurées garantissent la conformité au schéma dans la plupart des cas, il existe des scénarios où la sortie peut ne pas correspondre à votre schéma :

Refus (stop_reason: "refusal")

Claude maintient ses propriétés de sécurité et d'utilité même lors de l'utilisation des sorties structurées. Si Claude refuse une requête pour des raisons de sécurité :

• La réponse aura stop_reason: "refusal"
• Vous recevrez un code de statut 200
• Vous serez facturé pour les tokens générés
• La sortie peut ne pas correspondre à votre schéma (le refus a la priorité)

Limite de tokens atteinte (stop_reason: "max_tokens")

Si la réponse est coupée en raison de l'atteinte de la limite max_tokens :

• La réponse aura stop_reason: "max_tokens"
• La sortie peut être incomplète et ne pas correspondre à votre schéma
• Réessayez avec une valeur max_tokens plus élevée pour obtenir la sortie structurée complète

Erreurs de validation de schéma

Si votre schéma utilise des fonctionnalités non supportées ou est trop complexe, vous recevrez une erreur 400 :

« Trop de définitions récursives dans le schéma »

• Cause : Le schéma a des définitions récursives excessives ou cycliques
• Solution : Simplifiez la structure du schéma, réduisez la profondeur d'imbrication

« Le schéma est trop complexe »

• Cause : Le schéma dépasse les limites de complexité
• Solution : Divisez en schémas plus petits, simplifiez la structure ou réduisez le nombre d'outils marqués comme strict: true

Pour les problèmes persistants avec des schémas valides, contactez le support avec votre définition de schéma.

Compatibilité des fonctionnalités

Fonctionne avec :

• Traitement par lot : Traitez les sorties structurées à grande échelle avec une réduction de 50 %
• Comptage de tokens : Comptez les tokens sans compilation
• Streaming : Diffusez les sorties structurées comme les réponses normales
• Utilisation combinée : Utilisez les sorties JSON (output_format) et l'utilisation stricte d'outils (strict: true) ensemble dans la même requête

Incompatible avec :

• Citations : Les citations nécessitent l'entrelacement de blocs de citations avec du texte, ce qui entre en conflit avec les contraintes de schéma JSON strict. Retourne une erreur 400 si les citations sont activées avec output_format.
• Préfixage de message : Incompatible avec les sorties JSON