Capacités

Sorties structurées

Obtenez des résultats JSON validés à partir de flux de travail d'agents

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 d'outils et les entrées.

Les sorties structurées sont actuellement disponibles en tant que fonctionnalité bêta publique dans l'API Claude pour Claude Sonnet 4.5 et Claude Opus 4.1.

Pour utiliser la fonctionnalité, définissez l'en-tête bêta beta header structured-outputs-2025-11-13.

Partagez vos commentaires en utilisant ce formulaire.

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
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 d'agents

Démarrage rapide

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

Choisissez le bon mode pour votre cas d'usage :

Utilisez les sorties JSON quand	Utilisez l'utilisation stricte d'outils quand
Vous avez besoin de la réponse de Claude dans un format spécifique	Vous avez besoin de paramètres validés et de noms d'outils pour les appels d'outils
Extraction de données à partir d'images ou de texte	Création de flux de travail d'agents
Génération de rapports structurés	Garantir des appels de fonction type-safe
Formatage des réponses API	Outils complexes avec de nombreuses propriétés et/ou imbriquées

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

La création de systèmes d'agents 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
Pas besoin de valider et de réessayer les appels d'outils
Les agents prêts pour la production qui fonctionnent de manière cohérente à l'é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.

Sorties JSON uniquement

Les assistants SDK (Pydantic, Zod, parse()) ne fonctionnent qu'avec les sorties JSON (output_format).

Ces assistants transforment et valident la sortie de Claude pour vous. L'utilisation stricte d'outils valide l'entrée de Claude à vos outils, qui utilisent le champ input_schema existant dans les définitions d'outils.

Pour l'utilisation stricte d'outils, définissez votre input_schema directement dans la définition d'outil avec strict: true.

Méthodes spécifiques au 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.

La méthode parse() est disponible sur client.beta.messages, pas sur client.messages.

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 automatiquement les schémas fournis, cela vous donne le schéma transformé pour que vous puissiez le personnaliser davantage.

Comment fonctionne la transformation du SDK

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

Supprimez les contraintes non supportées (par exemple, minimum, maximum, minLength, maxLength)
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
Ajoutez additionalProperties: false à tous les objets
Filtrez les formats de chaîne à la liste supportée uniquement
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 à « 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 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 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, 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 d'outils)
- Changer uniquement les champs name ou description n'invalide pas le cache

Modification d'invite et coûts de 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 sera légèrement plus élevé
L'invite injectée vous coûte des jetons comme toute autre invite système
Changer le 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.

Les SDK Python et TypeScript peuvent automatiquement transformer les schémas avec des fonctionnalités non supportées en les supprimant et en ajoutant des contraintes aux descriptions de champs. Voir Méthodes spécifiques au SDK pour les détails.

Sorties invalides

Bien que les sorties structurées garantissent la conformité au schéma dans la plupart des cas, il y a 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 aura 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 (le refus a la priorité)

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 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 lots : Traitez les sorties structurées à l'échelle avec une réduction de 50 %
Comptage de 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_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 strictes du schéma JSON. Retourne une erreur 400 si les citations sont activées avec output_format.
Préfillage de messages : Incompatible avec les sorties JSON

Portée de la grammaire : Les grammaires s'appliquent uniquement à la sortie directe de Claude, pas aux appels d'outils, aux résultats d'outils ou aux balises de réflexion (lors de l'utilisation de Extended Thinking). L'état de la grammaire se réinitialise entre les sections, permettant à Claude de réfléchir librement tout en produisant une sortie structurée dans la réponse finale.

Capacités

Sorties structurées

Obtenez des résultats JSON validés à partir de flux de travail d'agents

Les sorties structurées sont actuellement disponibles en tant que fonctionnalité bêta publique dans l'API Claude pour Claude Sonnet 4.5 et Claude Opus 4.1.

Pour utiliser la fonctionnalité, définissez l'en-tête bêta beta header structured-outputs-2025-11-13.

Partagez vos commentaires en utilisant ce formulaire.

Pourquoi utiliser les sorties structurées

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
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 d'agents

Démarrage rapide

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

Choisissez le bon mode pour votre cas d'usage :

Utilisez les sorties JSON quand	Utilisez l'utilisation stricte d'outils quand
Vous avez besoin de la réponse de Claude dans un format spécifique	Vous avez besoin de paramètres validés et de noms d'outils pour les appels d'outils
Extraction de données à partir d'images ou de texte	Création de flux de travail d'agents
Génération de rapports structurés	Garantir des appels de fonction type-safe
Formatage des réponses API	Outils complexes avec de nombreuses propriétés et/ou imbriquées

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

L'utilisation stricte d'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
Les agents prêts pour la production qui fonctionnent de manière cohérente à l'échelle

Comment fonctionnent les sorties structurées

Travailler avec les sorties JSON dans les SDK

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.

Sorties JSON uniquement

Les assistants SDK (Pydantic, Zod, parse()) ne fonctionnent qu'avec les sorties JSON (output_format).

Pour l'utilisation stricte d'outils, définissez votre input_schema directement dans la définition d'outil avec strict: true.

Méthodes spécifiques au 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.

La méthode parse() est disponible sur client.beta.messages, pas sur client.messages.

Python : Assistant transform_schema()

Comment fonctionne la transformation du SDK

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

Supprimez les contraintes non supportées (par exemple, minimum, maximum, minLength, maxLength)
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
Ajoutez additionalProperties: false à tous les objets
Filtrez les formats de chaîne à la liste supportée uniquement
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.

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 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 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, 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 d'outils)
- Changer uniquement les champs name ou description n'invalide pas le cache

Modification d'invite et coûts de 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 sera légèrement plus élevé
L'invite injectée vous coûte des jetons comme toute autre invite système
Changer le 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 y a 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 aura 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 (le refus a la priorité)

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 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 lots : Traitez les sorties structurées à l'échelle avec une réduction de 50 %
Comptage de 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_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 strictes du schéma JSON. Retourne une erreur 400 si les citations sont activées avec output_format.
Préfillage de messages : Incompatible avec les sorties JSON

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)

Pourquoi utiliser les sorties structurées

Démarrage rapide

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

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

Comment fonctionnent les sorties structurées

Travailler avec les sorties JSON dans les SDK

Utilisation de Pydantic et Zod

Méthodes spécifiques au SDK

Exemple d'utilisation

Exemple d'utilisation

Comment fonctionne la transformation du SDK

Cas d'usage courants

Extraction de données (sorties JSON)

Considérations importantes

Compilation de grammaire et mise en cache

Modification d'invite et coûts de jetons

Limitations du schéma JSON

Fonctionnalités supportées

Non supporté

Support des motifs (regex)

Sorties invalides

Erreurs de validation de schéma

Compatibilité des fonctionnalités

Pourquoi utiliser les sorties structurées

Démarrage rapide

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

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

Comment fonctionnent les sorties structurées

Travailler avec les sorties JSON dans les SDK

Utilisation de Pydantic et Zod

Méthodes spécifiques au SDK

Exemple d'utilisation

Exemple d'utilisation

Comment fonctionne la transformation du SDK

Cas d'usage courants

Extraction de données (sorties JSON)

Considérations importantes

Compilation de grammaire et mise en cache

Modification d'invite et coûts de jetons

Limitations du schéma JSON

Fonctionnalités supportées

Non supporté

Support des motifs (regex)

Sorties invalides

Erreurs de validation de schéma

Compatibilité des fonctionnalités

Classification (sorties JSON)

Formatage des réponses API (sorties JSON)

Entrées d'outils validées (utilisation stricte d'outils)

Flux de travail d'agent avec plusieurs outils validés (utilisation stricte d'outils)