Sorties structurées

Les « structured outputs » (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 offrent deux fonctionnalités complémentaires :

• Sorties JSON (output_config.format) : obtenez la réponse de Claude dans un format JSON spécifique
• Utilisation d'outils stricte (strict: true) : garantissez 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 prompting 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 nouvelles 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()
• Typage sûr : types de champs et champs obligatoires garantis
• Fiable : 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 renvoie un JSON valide correspondant à votre schéma. Utilisez les sorties JSON lorsque vous devez :

• 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 des réponses d'API



Démarrage rapide

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    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_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
print(response.content[0].text)

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
}



Fonctionnement



Utilisation des sorties JSON dans les SDK

Les SDK fournissent des utilitaires qui facilitent l'utilisation des sorties JSON, notamment la transformation de schéma, la validation automatique et l'intégration avec des bibliothèques de schémas populaires.



Utilisation de 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 automatique du schéma via outputConfig(Class<T>)
• Ruby : classes Anthropic::BaseModel avec output_config: {format: Model}
• PHP : classes implémentant StructuredOutputModel avec outputConfig: ['format' => MyClass::class]
• C# : classes C# simples avec la surcharge générique Create<T>(), qui dérive le schéma automatiquement
• Go : structs Go reflétés automatiquement en schémas JSON sur l'API bêta, ou schémas JSON bruts via output_config
• CLI : schémas JSON bruts passés via output_config

from pydantic import BaseModel
from anthropic import Anthropic


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=1024,
    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

Chaque SDK fournit des utilitaires qui facilitent l'utilisation des sorties structurées. Consultez les pages individuelles des SDK pour tous les détails.



Fonctionnement de la transformation SDK

Les SDK Python, TypeScript, Ruby et PHP transforment automatiquement les schémas avec des fonctionnalités non prises en charge. Les SDK C# et Go appliquent les mêmes transformations lorsque le schéma est dérivé d'un type natif (Create<T>() en C# ; réflexion de struct ou BetaJSONSchemaOutputFormat() sur l'API bêta Go). Les étapes de transformation :

1. Supprimer les contraintes non prises en charge (par exemple, minimum, maximum, minLength, maxLength)
2. Mettre à jour les 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. Ajouter additionalProperties: false à tous les objets
4. Filtrer les formats de chaîne pour ne conserver que la liste prise en charge
5. Valider 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 via 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 en « Doit être au moins 100 » et valide la réponse par rapport à la contrainte d'origine.



Cas d'usage courants



Utilisation d'outils stricte

Pour appliquer la conformité JSON Schema sur les entrées d'outils avec un échantillonnage contraint par grammaire, consultez Utilisation d'outils stricte.



Utilisation conjointe des deux fonctionnalités

Les sorties JSON et l'utilisation d'outils stricte 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 d'outils stricte valide les paramètres d'outils (comment Claude appelle vos fonctions)

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

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # Sorties JSON : format de réponse structuré
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # Utilisation d'outils stricte : paramètres d'outil garantis
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)



Considérations importantes



Compilation et mise en cache de la grammaire

Les sorties structurées utilisent un é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 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 conjointe des sorties structurées et de l'utilisation d'outils)
  • Modifier uniquement les champs name ou description n'invalide pas le cache



Modification du prompt 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 que :

• Votre nombre de tokens d'entrée est légèrement plus élevé
• Le prompt injecté vous coûte des tokens comme toute autre invite système
• Modifier le paramètre output_config.format invalidera toute mise en cache des prompts pour ce fil de conversation



Limitations de JSON Schema

Les sorties structurées prennent en charge JSON Schema standard avec certaines limitations. Les sorties JSON et l'utilisation d'outils stricte partagent ces limitations.



Ordre des propriétés

Lors de l'utilisation des sorties structurées, les propriétés dans les objets conservent leur ordre défini dans votre schéma, avec une mise en garde importante : les propriétés obligatoires 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 (obligatoire, dans l'ordre du schéma)
2. email (obligatoire, 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 obligatoires, ou tenez compte de cette réorganisation 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 conserve 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 a 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 tronqué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. 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 du tableau précédent, 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 entre elles de manières qui peuvent 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 du tableau précédent est satisfaite. Comme dernier garde-fou, l'API applique également un délai d'expiration 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 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 cette option aux outils où les violations de schéma causent de vrais problèmes, et comptez sur l'adhérence naturelle de Claude pour les outils plus simples.

2. Réduisez les paramètres optionnels. Rendez les paramètres required lorsque c'est 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 obligatoire et de faire en sorte que Claude fournisse explicitement cette valeur par défaut.

3. Simplifiez les structures imbriquées. Les objets profondément imbriqués avec des champs optionnels aggravent la complexité. Aplatissez les structures lorsque c'est 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 distincts.

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 prompts et les réponses sont traités avec ZDR lors de l'utilisation des sorties structurées. Cependant, le schéma JSON lui-même est temporairement mis en cache jusqu'à 24 heures depuis la dernière utilisation à des fins d'optimisation. Aucune donnée de prompt 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 incluses 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 prompts 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 (prompts et réponses), où elles sont protégées par les garanties HIPAA.

Pour l'éligibilité ZDR et HIPAA sur toutes les fonctionnalités, consultez 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 de tokens : comptez les tokens sans compilation
• Streaming : diffusez les sorties structurées comme des réponses normales
• Utilisation combinée : utilisez les sorties JSON (output_config.format) et l'utilisation d'outils stricte (strict: true) ensemble dans la même requête

Incompatible avec :

• Citations : les citations nécessitent d'intercaler des blocs de citation avec du texte, ce qui entre en conflit avec les contraintes strictes du schéma JSON. Renvoie une erreur 400 si les citations sont activées avec output_config.format.
• Préremplissage de message : incompatible avec les sorties JSON