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. Deux fonctionnalités complémentaires sont disponibles :

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

Ces fonctionnalités peuvent être utilisées 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 malformées ou des entrées d'outils invalides qui cassent vos applications. Même avec un prompting soigneux, 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 nouvelles tentatives

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

• Toujours valides : Plus d'erreurs JSON.parse()
• Sûres pour les types : Types de champs et champs obligatoires garantis
• Fiables : Aucune nouvelle 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 du 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 d'images ou de texte
• Générer des rapports structurés
• Formater des réponses d'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 fonctionne

Travailler avec les sorties JSON dans les SDK

Les SDK fournissent des helpers 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émas populaires.

Utilisation des 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()
• Java : classes Java simples avec dérivation automatique de schéma via outputFormat(Class<T>)
• Ruby : classes Anthropic::BaseModel avec output_config: {format: Model}
• C#, Go, PHP : schémas JSON bruts passés via output_config

Méthodes spécifiques aux SDK

Chaque SDK fournit des helpers qui facilitent le travail avec les sorties structurées. Consultez les pages individuelles des SDK pour tous les détails.

Fonctionnement de la transformation SDK

Les SDK Python et TypeScript transforment automatiquement les schémas avec des fonctionnalités non prises en charge :

1. Suppression des contraintes non prises en charge (par exemple, minimum, maximum, minLength, maxLength)
2. Mise à jour des descriptions avec les informations de contrainte (par exemple, "Doit être au moins 100"), lorsque la contrainte n'est pas directement prise en charge avec les sorties structurées
3. Ajout de additionalProperties: false à tous les objets
4. Filtrage des formats de chaîne vers la liste prise en charge uniquement
5. Validation des 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 via 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 originale.

Cas d'utilisation courants

Utilisation stricte des outils

L'utilisation stricte des outils valide les paramètres des outils, garantissant que Claude appelle vos fonctions avec des arguments correctement typés. Utilisez l'utilisation stricte des outils lorsque vous avez besoin de :

• Valider les paramètres des outils
• Construire des workflows agentiques
• Garantir des appels de fonction type-safe
• Gérer des outils complexes avec des propriétés imbriquées

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

La construction de systèmes agentiques fiables nécessite une conformité garantie au schéma. Sans mode strict, Claude pourrait retourner des types incompatibles ("2" au lieu de 2) ou des champs requis manquants, cassant vos fonctions et provoquant des erreurs d'exécution.

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

• Les fonctions reçoivent des arguments correctement typés à chaque fois
• Pas besoin de valider et de réessayer les appels d'outils
• Des 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 mode strict, Claude pourrait fournir passengers: "two" ou passengers: "2". Avec strict: true, la réponse contiendra toujours passengers: 2.

Démarrage rapide

Format de réponse : Blocs d'utilisation d'outils avec des entrées validées dans response.content[x].input

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

Garanties :

• L'input de l'outil suit strictement l'input_schema
• Le name de l'outil est toujours valide (parmi les outils fournis ou les outils serveur)

Fonctionnement

Cas d'utilisation courants

Utiliser les deux fonctionnalités ensemble

Les sorties JSON et l'utilisation stricte des outils résolvent des problèmes différents et peuvent être utilisées 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)

Combinées, Claude peut appeler des outils avec des paramètres garantis valides ET retourner des réponses JSON structurées. Cela est utile pour les flux de travail agentiques 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 un échantillonnage contraint avec des artefacts de grammaire compilés. Cela introduit certaines caractéristiques de performance à prendre en compte :

• Latence de la première requête : La première fois que vous utilisez un schéma spécifique, il y aura une latence supplémentaire pendant la compilation de la grammaire
• 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 combinée des sorties structurées et de l'utilisation des outils)
  • Modifier uniquement les champs name ou description n'invalide pas le cache

Modification des invites 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
• Modifier le paramètre output_config.format invalidera tout cache d'invite pour ce fil de conversation

Limitations du schéma JSON

Les sorties structurées prennent en charge le schéma JSON standard avec quelques limitations. Les sorties JSON et l'utilisation stricte des outils partagent ces limitations.

Ordre des propriétés

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

Par exemple, avec 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 suit :

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, assurez-vous que toutes les propriétés sont marquées 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 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 car le message de refus a la priorité sur les contraintes du schéma

Limite de tokens atteinte (stop_reason: "max_tokens")

Si la réponse est interrompue 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

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. Des schémas plus complexes produisent des grammaires plus grandes qui prennent plus de temps à compiler. Pour se protéger contre des 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 parce que 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 à rendre la grammaire compilée disproportionnellement 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 de compilation de 180 secondes. Les schémas qui passent toutes les vérifications explicites mais produisent des grammaires compilées très grandes peuvent atteindre ce délai.

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

Si vous atteignez des 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 dans la mesure du possible. Chaque paramètre optionnel double approximativement une partie de l'espace d'états de la grammaire. Si un paramètre a toujours une valeur par défaut raisonnable, envisagez de le rendre requis et de demander à Claude de fournir explicitement cette valeur par défaut.

3. Simplifiez les structures imbriquées. Les objets profondément imbriqués avec des champs optionnels amplifient la complexité. Aplatissez les structures dans la mesure du possible.

4. Divisez en plusieurs requêtes. Si vous avez de nombreux outils stricts, envisagez de les répartir sur des requêtes ou des sous-agents séparés.

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 des 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 API.

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

Compatibilité des fonctionnalités

Compatible avec :

• Traitement par lots : Traitez des sorties structurées à grande échelle avec 50 % de réduction
• Comptage de tokens : Comptez les tokens sans compilation
• Streaming : Diffusez des sorties structurées comme des 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 l'entrelacement de 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é-remplissage de messages : Incompatible avec les sorties JSON