Sorties structurées
Obtenez des résultats JSON validés à partir de workflows d’agents
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, par exemple pour extraire des données d’images ou de texte, générer des rapports structurés ou formater des réponses d’API. Cette page couvre les sorties JSON. - Utilisation stricte d’outils (
strict: true) : garantissez la validation du schéma sur les noms et les entrées des outils. Consultez Utilisation stricte d’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 pourriez 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 de nouvelles tentatives
Les sorties structurées garantissent des réponses conformes au schéma grâce au « constrained decoding » (décodage contraint) :
- Toujours valides : aucune erreur d’analyse JSON
- Typage sûr : types de champs et champs obligatoires garantis
- Fiables : aucune nouvelle tentative nécessaire pour les violations de schéma
Fonctionnement
Définissez votre schéma
Décrivez la structure souhaitée sous forme de schéma JSON ou de type dans votre langage. Le schéma suit JSON Schema, avec certaines limitations.
Envoyez-le dans output_config.format
La requête transporte le schéma dans
output_config.formatavectype: "json_schema". Les helpers du SDK le définissent pour vous.Lisez la réponse
Claude renvoie un JSON valide correspondant à votre schéma dans le bloc de contenu texte de la réponse. Les helpers du SDK l’analysent dans votre type.
Utilisation
from pydantic import BaseModel
class ContactInfo(BaseModel):
name: str
email: str
plan_interest: str
demo_requested: bool
client = Anthropic()
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": (
"Extract the key information from this email: "
"John Smith (john@example.com) is interested in our Enterprise plan "
"and wants to schedule a demo for next Tuesday at 2pm."
),
}
],
output_format=ContactInfo,
)
print(response.parsed_output)Passez un modèle Pydantic à client.messages.parse(), la méthode recommandée, en tant que output_format. Le SDK transforme le schéma du modèle, l’envoie en tant que output_config.format, valide la réponse et renvoie le modèle analysé dans parsed_output.
L’exemple précédent produit :
name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=TrueSi vous connaissez les clés d’un champ, utilisez un modèle Pydantic imbriqué, et non un dict. Le SDK envoie un champ dict sous forme d’objet avec des properties vides, Claude ne peut donc renvoyer que {} pour celui-ci. Si vous ne connaissez pas les clés à l’avance, consultez Objets avec des clés arbitraires.
Fonctionnement de la transformation par le SDK
La plupart des helpers du SDK transforment les schémas qui utilisent des fonctionnalités non prises en charge. Les étapes de transformation :
- Suppression des contraintes non prises en charge (par exemple,
minimum,maximum,minLength,maxLength) - Mise à jour des descriptions en ajoutant chaque contrainte non prise en charge à la description du champ (par exemple,
{minimum: 100}) - Ajout de
additionalProperties: falseà tous les objets - Filtrage des formats de chaîne pour ne conserver que la liste prise en charge
- Validation des réponses par rapport à votre schéma d’origine et toutes ses contraintes, si le helper valide les réponses
Claude reçoit un schéma simplifié, mais un helper qui valide les réponses applique toujours chaque contrainte dans votre code.
Exemple : un champ avec minimum: 100 devient un simple entier dans le schéma envoyé, et le SDK ajoute {minimum: 100} à la description du champ. Un helper qui valide les réponses vérifie toujours la réponse par rapport à minimum: 100.
Utiliser un schéma JSON brut
Pour utiliser un schéma JSON provenant d’un fichier, d’une spécification OpenAPI ou d’un code qui le construit à l’exécution, passez-le dans output_config.format.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": (
"Extract the key information from this email: "
"John Smith (john@example.com) 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,
},
}
},
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)L’exemple précédent produit :
{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}Pour déplacer les contraintes non prises en charge par l’API dans les descriptions des champs, faites passer le schéma par transform_schema() du package anthropic avant de l’envoyer, et modifiez le résultat si nécessaire. transform_schema() accepte également un modèle Pydantic. Contrairement à client.messages.parse(), il renvoie le schéma transformé au lieu de l’envoyer.
Cas d’utilisation courants
Extrayez des données structurées à partir de texte non structuré :
from pydantic import BaseModel
class LineItem(BaseModel):
description: str
quantity: float
unit_price: float
class Invoice(BaseModel):
invoice_number: str
date: str
total_amount: float
line_items: list[LineItem]
customer_name: str
client = anthropic.Anthropic()
invoice_text = """
Invoice #12345
Date: 2024-01-15
Customer: Acme Corp
2 widgets at $150.00 each
1 setup fee at $200.00
Total: $500.00
"""
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=4096,
output_format=Invoice,
messages=[
{"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
],
)
print(response.parsed_output)Classez du contenu avec des catégories structurées :
from pydantic import BaseModel
client = Anthropic()
class Classification(BaseModel):
category: str
confidence: float
tags: list[str]
sentiment: str
feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
output_format=Classification,
messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)
print(response.parsed_output)Générez des réponses prêtes pour l’API :
from pydantic import BaseModel
client = Anthropic()
class Payload(BaseModel):
message: str
class APIError(BaseModel):
code: str
detail: str
class Metadata(BaseModel):
request_id: str
class APIResponse(BaseModel):
status: str
data: Payload
errors: list[APIError] | None = None
metadata: Metadata
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
output_format=APIResponse,
messages=[
{
"role": "user",
"content": "Write an API response: request req_2abc3def has an invalid email.",
}
],
)
print(response.parsed_output)Utilisation stricte d’outils
Pour imposer la conformité à JSON Schema sur les entrées d’outils avec un échantillonnage contraint par grammaire, consultez Utilisation stricte d’outils.
Utiliser les deux fonctionnalités ensemble
Les sorties JSON et l’utilisation stricte d’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 d’outils valide les paramètres des outils (comment Claude appelle vos fonctions).
Combinées, elles permettent à Claude d’appeler des outils avec des paramètres garantis valides ET de 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.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
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'outils 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 « latency » (latence) supplémentaire pendant la compilation de la grammaire.
- Mise en cache automatique : les grammaires compilées sont mises en cache pendant 24 heures à compter 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 ou, lorsque vous utilisez à la fois les sorties structurées et l’utilisation d’outils, l’ensemble des outils de votre requête. Modifier uniquement les champs
nameoudescriptionn’invalide pas le cache.
Modification du prompt et coûts en tokens
Lorsque vous utilisez les sorties structurées, Claude reçoit automatiquement une « system prompt » (invite système) supplémentaire expliquant le format de sortie attendu. Cela signifie :
- 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.formatinvalide tout cache de prompts pour ce fil de conversation.
Limitations de JSON Schema
Les sorties structurées prennent en charge le JSON Schema standard avec certaines limitations. Les sorties JSON et l’utilisation stricte d’outils partagent ces limitations.
- Tous les types de base : object, array, string, integer, number, boolean, null
enumetconst(chaînes, nombres, booléens ou nulls uniquement), avec une mise en garde concernant la casseanyOfetallOf, à l’exception des usages listés sous « Non pris en charge »$ref,$defsetdefinitions- Propriété
defaultpour tous les types pris en charge requiredetadditionalProperties(doit être défini surfalsepour les objets)- Formats de chaîne :
date-time,time,date,duration,email,hostname,uri,ipv4,ipv6,uuid minItemspour les tableaux (seules les valeurs 0 et 1 sont prises en charge)
- Schémas récursifs
oneOf(utilisez plutôtanyOf)notanyOfdans le même objet de schéma que des mots-clés tels quetypeouproperties(les annotations telles quetitleetdescriptionsont acceptées)allOfavec des schémas en conflit (par exemple, des valeurstypedifférentes)allOfavec deux schémas ou plus lorsque l’un d’eux contient directement$ref,anyOfouallOf- Types complexes dans les enums
$refexterne (par exemple,'$ref': 'http://...')- Contraintes numériques (telles que
minimum,maximum,multipleOf) - Contraintes de chaîne (
minLength,maxLength) - Contraintes de tableau au-delà de
minItemsde 0 ou 1 additionalPropertiesdéfini sur autre chose quefalse(consultez Objets avec des clés arbitraires)
Si vous utilisez une fonctionnalité non prise en charge, vous recevrez une erreur 400 avec des détails.
Fonctionnalités regex prises en charge :
- Correspondance complète (
^...$) et correspondance partielle - Quantificateurs :
*,+,?, cas simples de{n,m} - Classes de caractères :
[],.,\d,\w,\s - Groupes :
(...)
Non pris en charge :
- Références arrière vers des groupes (par exemple,
\1,\2) - Assertions lookahead/lookbehind (par exemple,
(?=...),(?!...)) - Limites de mots :
\b,\B - Quantificateurs
{n,m}complexes avec de grandes plages
Les motifs regex simples fonctionnent bien. Les motifs complexes peuvent entraîner des erreurs 400.
Objets avec des clés arbitraires
Listez chaque clé d’un objet, soit dans properties, soit en tant que champ de la classe ou du schéma que vous passez au SDK. Comme additionalProperties doit être false, Claude ne peut renvoyer que les clés que vous listez.
L’API accepte un objet dont les properties sont vides ou absentes, mais Claude ne peut renvoyer que {} pour celui-ci. Un type map, dictionnaire ou record ne liste aucune clé, les SDK Python et TypeScript l’envoient donc sous forme d’objet avec des properties vides. Les SDK Java et Ruby lèvent plutôt une erreur.
Si vous ne connaissez pas les clés à l’avance, utilisez plutôt un tableau. Donnez à chaque élément une key et une value, comme dans ce schéma :
{
"type": "array",
"items": {
"type": "object",
"properties": {
"key": { "type": "string" },
"value": { "type": "string" }
},
"required": ["key", "value"],
"additionalProperties": false
}
}Ordre des propriétés
Lorsque vous utilisez les sorties structurées, les propriétés des objets conservent l’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 facultatives.
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 ordonne les propriétés ainsi :
name(obligatoire, dans l’ordre du schéma)email(obligatoire, dans l’ordre du schéma)notes(facultative, dans l’ordre du schéma)age(facultative, dans l’ordre du schéma)
Cela signifie que la sortie pourrait ressembler à :
{
"name": "John Smith",
"email": "john@example.com",
"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 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 pourrait 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 pourrait ne pas correspondre à votre schéma, car le message de refus prend le pas sur les contraintes du schéma.
Une propriété qui demande la réflexion du modèle ou un raisonnement étape par étape peut entraîner un refus reasoning_extraction. Demandez plutôt une courte explication. Consultez Conserver le raisonnement dans les blocs de réflexion.
Limite de tokens atteinte (stop_reason: "max_tokens")
Si la réponse est coupée parce qu’elle a atteint la limite max_tokens :
- La réponse a
stop_reason: "max_tokens". - La sortie pourrait être incomplète et ne pas correspondre à votre schéma.
- Réessayez avec une valeur
max_tokensplus élevée pour obtenir la sortie structurée complète.
Casse des valeurs enum
Les sorties structurées ne garantissent pas la casse des valeurs de chaîne enum et const : Claude peut renvoyer une valeur qui ne diffère de votre schéma que par la casse, généralement pour la première lettre d’un mot suivant une espace. Par exemple, avec ce schéma :
{
"type": "string",
"enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}La sortie pourrait contenir "Conversation Topic 3" (avec un « T » majuscule) même si cette valeur exacte ne figure pas dans l’enum. La réponse se termine normalement, sans erreur ni stop_reason particulier. Cela s’applique aussi bien aux sorties JSON qu’à l’utilisation stricte d’outils. Comparez les valeurs enum sans tenir compte de la casse, et évitez les valeurs enum qui ne diffèrent que par la casse.
Limites de complexité des schémas
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 volumineuses dont la compilation prend plus de temps. Pour se protéger contre des temps de compilation excessifs, l’API impose plusieurs limites de complexité.
Limites explicites
Les limites suivantes s’appliquent à toutes les requêtes avec output_config.format ou strict: true :
| Limite | Valeur | Description |
|---|---|---|
| Outils stricts par requête | 20 | Nombre maximal d’outils avec strict: true. Les outils non stricts ne comptent pas dans cette limite. |
| Paramètres facultatifs | 24 | Total des paramètres facultatifs dans tous les schémas d’outils stricts et schémas de sortie JSON. Chaque paramètre non listé dans required compte dans cette limite. |
| Paramètres avec types union | 16 | Total des paramètres qui utilisent anyOf ou des tableaux de types (par exemple, "type": ["string", "null"]) dans tous les schémas stricts. Ceux-ci sont particulièrement coûteux car ils créent un coût de compilation exponentiel. |
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é d’un schéma ne se réduit pas à une seule dimension : des fonctionnalités telles que les paramètres facultatifs, les types union, les objets imbriqués et le nombre d’outils interagissent de manière à pouvoir rendre la grammaire compilée disproportionnellement volumineuse.
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 respectée. En dernier recours, l’API impose é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 volumineuses peuvent atteindre ce délai.
Conseils pour réduire la complexité des schémas
Si vous atteignez les limites de complexité, essayez ces stratégies dans l’ordre :
-
Marquez uniquement les outils critiques comme stricts. Si vous avez de nombreux outils, réservez l’utilisation stricte d’outils à ceux pour lesquels les violations de schéma causent de réels problèmes, et comptez sur le respect naturel de Claude pour les outils plus simples.
-
Réduisez les paramètres facultatifs. Rendez les paramètres
requireddans la mesure du possible. Chaque paramètre facultatif 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 demander à Claude de fournir explicitement cette valeur par défaut. -
Simplifiez les structures imbriquées. Les objets profondément imbriqués avec des champs facultatifs aggravent la complexité. Aplatissez les structures dans la mesure du possible.
-
Répartissez sur plusieurs requêtes. Si vous avez de nombreux outils stricts, envisagez de les répartir sur des requêtes distinctes ou des sous-agents.
Pour des problèmes persistants avec des schémas valides, contactez le support en fournissant la définition de votre schéma.
Migration depuis la bêta
Le paramètre output_format a été déplacé vers output_config.format, et les en-têtes bêta ne sont plus nécessaires. Le paramètre output_format est déprécié. Pour l’utiliser malgré tout, ajoutez l’en-tête bêta structured-outputs-2025-11-13. Sans celui-ci, l’API renvoie une erreur 400.
Dans le SDK Python (v1.0 et versions ultérieures), un dictionnaire de schéma passé en tant que output_format={...} lève une TypeError. Utilisez plutôt output_config. Un modèle Pydantic passé en tant que output_format=Model à parse() ou stream() fonctionne sans modification et sans en-tête bêta, car le SDK l’envoie en tant que output_config. Consultez Utiliser un schéma JSON brut pour la forme mise à jour de l’API.
Compatibilité des fonctionnalités
Fonctionne avec :
- Traitement par lots : traitez des sorties structurées à grande échelle avec une remise de 50 pour cent
- Comptage de tokens : comptez les tokens sans compilation
- Streaming : diffusez les sorties structurées en streaming comme des réponses normales
- Utilisation combinée : utilisez les sorties JSON (
output_config.format) et l’utilisation stricte d’outils (strict: true) ensemble dans la même requête
Incompatible avec :
- Citations : les citations nécessitent d’entrelacer des blocs de citation avec du texte, ce qui entre en conflit avec les contraintes strictes du schéma JSON. L’API renvoie une erreur 400 si les citations sont activées avec
output_config.format. Pour extraire des données structurées avec une citation pour chaque valeur, consultez Obtenir des données structurées avec des citations. - Préremplissage des messages : le préremplissage est incompatible avec les sorties JSON.
Disponibilité
Claude API
- API
- Messages API
- Managed Agents Non pris en charge
- Modèles
- Tous les modèles
Amazon Bedrock
- API
- Messages API
- Modèles
- Tous les modèles
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modèles
- Tous les modèles
Claude Platform on AWS
- API
- Messages API
- Managed Agents Non pris en charge
- Modèles
- Tous les modèles
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents Non pris en charge
- Modèles
- Tous les modèles
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modèles
- Tous les modèles
Microsoft Foundry
- API
- Messages API
- Modèles
- Tous les modèles
Traitement des données
Présentation du traitement des donnéesPoints de terminaison concernés
/v1/messages
Exclut Modèles couverts
Vos prompts et les sorties de Claude ne sont pas stockés. Seul le JSON Schema est mis en cache, pendant 24 heures au maximum après sa dernière utilisation. Cela couvre également l’utilisation d’outils stricte (strict: true sur les outils), qui utilise le même pipeline de grammaire. En savoir plus
Les PHI ne doivent pas être incluses dans les définitions de JSON Schema ; consultez les consignes de traitement des PHI. En savoir plus
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 bénéficient pas des mêmes protections PHI que les prompts et les réponses. N’incluez pas de PHI dans les noms de propriétés du 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.
Étapes suivantes
Demandez à Claude de citer ses sources lorsqu’il répond à des questions sur des documents fournis.
Imposez la conformité à JSON Schema sur les entrées d’outils de Claude avec un échantillonnage contraint par grammaire.
Connectez Claude à des outils et API externes. Découvrez où s’exécutent les outils et comment fonctionne la boucle agentique.
Découvrez la structure tarifaire d’Anthropic pour les modèles et les fonctionnalités.
Cette page vous a-t-elle été utile ?