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. Les sorties structurées fournissent deux fonctionnalités complémentaires :

• Sorties JSON (output_config.format) : Obtenir la réponse de Claude dans un format JSON spécifique
• Utilisation stricte des outils (strict: true) : Garantir la validation du schéma sur les noms et les entrées des outils

Vous pouvez utiliser ces fonctionnalités indépendamment ou ensemble dans la même requête.

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 sûr : Types de champs garantis et champs obligatoires
• Fiable : Aucune tentative nécessaire pour les violations de schéma

Sorties JSON

Les sorties JSON contrôlent le format de réponse de Claude, garantissant que Claude retourne un JSON valide correspondant à votre schéma. Utilisez les sorties JSON lorsque vous avez besoin de :

• Contrôler le format de réponse de Claude
• Extraire des données à partir d'images ou de texte
• Générer des rapports structurés
• Formater les réponses API

Démarrage rapide

Format de réponse : JSON valide correspondant à votre schéma dans response.content[0].text

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

Comment ça marche

Travailler avec les sorties JSON dans les SDKs

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

Utiliser les définitions de schéma natives

Au lieu d'écrire des schémas JSON bruts, vous pouvez utiliser des outils de définition de schéma familiers dans votre langage :

• Python : modèles Pydantic avec client.messages.parse()
• TypeScript : schémas Zod avec zodOutputFormat() ou littéraux JSON Schema typés avec jsonSchemaOutputFormat()
• Java : classes Java simples avec dérivation de schéma automatique via outputConfig(Class<T>)
• Ruby : classes Anthropic::BaseModel avec output_config: {format: Model}
• PHP : classes implémentant StructuredOutputModel avec outputConfig: ['format' => MyClass::class]
• CLI, C#, : schémas JSON bruts passés via

Méthodes spécifiques au SDK

Chaque SDK fournit des assistants qui facilitent le travail avec les sorties structurées. Consultez les pages individuelles du SDK pour plus de détails.

Comment fonctionne la transformation du SDK

Les SDKs Python, TypeScript, Ruby et PHP transforment automatiquement les schémas avec des fonctionnalités non supportées :

1. Supprimer les contraintes non supportées (par exemple, minimum, maximum, minLength, maxLength)
2. Mettre à 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. Ajouter additionalProperties: false à tous les objets
4. Filtrer les formats de chaîne à la liste supportée uniquement
5. Valider les réponses par rapport à votre schéma original (avec toutes les contraintes)

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

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

Cas d'usage courants

Utilisation stricte des outils

Pour appliquer la conformité du schéma JSON sur les entrées d'outils avec l'échantillonnage contraint par grammaire, consultez Utilisation stricte des outils.

Utiliser les deux fonctionnalités ensemble

Les sorties JSON et l'utilisation stricte des outils résolvent des problèmes différents et fonctionnent ensemble :

• Les sorties JSON contrôlent le format de réponse de Claude (ce que Claude dit)
• L'utilisation stricte des outils valide les paramètres des outils (comment Claude appelle vos fonctions)

Lorsqu'elles sont combinées, Claude peut appeler des outils avec des paramètres garantis valides ET retourner des réponses JSON structurées. Ceci est utile pour les flux de travail d'agents où vous avez besoin à la fois d'appels d'outils fiables et de sorties finales structurées.

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 la première requête : La première fois que vous utilisez un schéma spécifique, il y a une latence supplémentaire pendant que la grammaire se compile
• Mise en cache automatique : Les grammaires compilées sont mises en cache pendant 24 heures à partir de la dernière utilisation, ce qui rend 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 des outils)
  • La modification uniquement des champs name ou description n'invalide pas le cache

Modification des invites et coûts en jetons

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

• Votre nombre de jetons d'entrée est légèrement plus élevé
• L'invite injectée vous coûte des jetons comme toute autre invite système
• La modification du paramètre output_config.format invalidera tout cache d'invite 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 des outils partagent ces limitations.

Ordre des propriétés

Lors de l'utilisation de sorties structurées, les propriétés dans les objets maintiennent leur ordre défini à partir de votre schéma, avec une mise en garde importante : les propriétés requises apparaissent en premier, suivies par les propriétés optionnelles.

Par exemple, étant donné ce schéma :

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

La sortie ordonnera les propriétés comme :

1. name (requis, dans l'ordre du schéma)
2. email (requis, dans l'ordre du schéma)
3. notes (optionnel, dans l'ordre du schéma)
4. age (optionnel, dans l'ordre du schéma)

Cela signifie que la sortie pourrait ressembler à :

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

Si l'ordre des propriétés dans la sortie est important pour votre application, marquez toutes les propriétés comme requises, ou tenez compte de ce réordonnancement dans votre logique d'analyse.

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 de sorties structurées. Si Claude refuse une requête pour des raisons de sécurité :

• La réponse a stop_reason: "refusal"
• Vous recevrez un code de statut 200
• Vous serez facturé pour les jetons générés
• La sortie peut ne pas correspondre à votre schéma car le message de refus prend la priorité sur les contraintes de schéma

Limite de jetons 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 a 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

Limites de complexité du schéma

Les sorties structurées fonctionnent en compilant vos schémas JSON en une grammaire qui contraint la sortie de Claude. Les schémas plus complexes produisent des grammaires plus grandes qui prennent plus de temps à compiler. Pour se protéger contre les temps de compilation excessifs, l'API applique plusieurs limites de complexité.

Limites explicites

Les limites suivantes s'appliquent à toutes les requêtes avec output_config.format ou strict: true :

Limites internes supplémentaires

Au-delà des limites explicites ci-dessus, il existe des limites internes supplémentaires sur la taille de la grammaire compilée. Ces limites existent car la complexité du schéma ne se réduit pas à une seule dimension : des fonctionnalités comme les paramètres optionnels, les types union, les objets imbriqués et le nombre d'outils interagissent les uns avec les autres de manière à pouvoir rendre la grammaire compilée disproportionnément grande.

Lorsque ces limites sont dépassées, vous recevrez une erreur 400 avec le message « Schema is too complex for compilation ». Ces erreurs signifient que la complexité combinée de vos schémas dépasse ce qui peut être compilé efficacement, même si chaque limite individuelle ci-dessus est satisfaite. En dernier recours, l'API applique également un délai d'expiration de compilation de 180 secondes. Les schémas qui passent tous les contrôles explicites mais produisent des grammaires compilées très grandes peuvent atteindre ce délai d'expiration.

Conseils pour réduire la complexité du schéma

Si vous atteignez les limites de complexité, essayez ces stratégies dans l'ordre :

1. Marquez uniquement les outils critiques comme stricts. Si vous avez de nombreux outils, réservez-le aux outils où les violations de schéma causent de vrais problèmes, et fiez-vous à l'adhérence naturelle de Claude pour les outils plus simples.

2. Réduisez les paramètres optionnels. Rendez les paramètres required si possible. Chaque paramètre optionnel double approximativement une partie de l'espace d'état de la grammaire. Si un paramètre a toujours une valeur par défaut raisonnable, envisagez de le rendre requis et d'avoir Claude fournir cette valeur par défaut explicitement.

3. Simplifiez les structures imbriquées. Les objets profondément imbriqués avec des champs optionnels composent la complexité. Aplatissez les structures si possible.

4. Divisez en plusieurs requêtes. Si vous avez de nombreux outils stricts, envisagez de les diviser entre plusieurs requêtes ou sous-agents.

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

Conservation des données

Les invites et les réponses sont traitées avec ZDR lors de l'utilisation de sorties structurées. Cependant, le schéma JSON lui-même est temporairement mis en cache pendant jusqu'à 24 heures depuis la dernière utilisation à des fins d'optimisation. Aucune donnée d'invite ou de réponse n'est conservée au-delà de la réponse de l'API.

Les sorties structurées sont éligibles à HIPAA, mais les PHI ne doivent pas être inclus dans les définitions de schéma JSON. L'API compile les schémas JSON en grammaires qui sont mises en cache séparément du contenu des messages, et ces schémas mis en cache ne reçoivent pas les mêmes protections PHI que les invites et les réponses. N'incluez pas de PHI dans les noms de propriétés de schéma, les valeurs enum, les valeurs const ou les expressions régulières pattern. Les PHI ne doivent apparaître que dans le contenu des messages (invites et réponses), où ils sont protégés par les garanties de sécurité HIPAA.

Pour l'éligibilité ZDR et HIPAA dans toutes les fonctionnalités, voir API et conservation des données.

Compatibilité des fonctionnalités

Fonctionne avec :

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

Incompatible avec :

• Citations : Les citations nécessitent d'entrelacer les blocs de citation avec du texte, ce qui entre en conflit avec les contraintes strictes du schéma JSON. Retourne une erreur 400 si les citations sont activées avec output_config.format.
• Préfixage de messages : Incompatible avec les sorties JSON