Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 :
output_config.format) : obtenez la réponse de Claude dans un format JSON spécifiquestrict: true) : garantissez la validation du schéma sur les noms et les entrées des outilsVous pouvez utiliser ces fonctionnalités indépendamment ou ensemble dans la même requête.
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 :
Les sorties structurées garantissent des réponses conformes au schéma grâce au décodage contraint :
JSON.parse()Les sorties JSON contrôlent le format de réponse de Claude, garantissant que Claude renvoie du JSON valide correspondant à votre schéma. Utilisez les sorties JSON lorsque vous devez :
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
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(next(block.text for block in response.content if block.type == "text"))Format de réponse : JSON valide correspondant à votre schéma dans le bloc de contenu texte de la réponse
{
"name": "John Smith",
"email": "[email protected]",
"plan_interest": "Enterprise",
"demo_requested": true
}Définissez votre schéma JSON
Créez un schéma JSON qui décrit la structure que vous souhaitez que Claude suive. Le schéma utilise le format JSON Schema standard avec certaines limitations (voir Limitations de JSON Schema).
Ajoutez le paramètre output_config.format
Incluez le paramètre output_config.format dans votre requête API avec type: "json_schema" et votre définition de schéma.
Analysez la réponse
La réponse de Claude est du JSON valide correspondant à votre schéma, renvoyé dans le bloc de contenu texte de la réponse.
Les SDK fournissent des utilitaires qui facilitent le travail avec les sorties JSON, notamment la transformation de schéma, la validation automatique et l'intégration avec des bibliothèques de schémas populaires.
Au lieu d'écrire des schémas JSON bruts, vous pouvez utiliser des outils de définition de schéma familiers dans votre langage :
client.messages.parse()zodOutputFormat() ou littéraux JSON Schema typés avec jsonSchemaOutputFormat()outputConfig(Class<T>)Anthropic::BaseModel avec output_config: {format: Model}StructuredOutputModel avec outputConfig: ['format' => MyClass::class]Create<T>(), qui dérive le schéma automatiquementoutput_configoutput_configfrom 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-5",
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)Chaque SDK fournit des utilitaires qui facilitent le travail avec les sorties structurées. Consultez les pages individuelles des SDK pour tous les détails.
client.messages.parse() (Recommandé)
La méthode parse() transforme automatiquement votre modèle Pydantic, valide la réponse et renvoie un attribut parsed_output.
from pydantic import BaseModel
class ContactInfo(BaseModel):
name: str
email: str
plan_interest: str
response = client.messages.parse(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Extract contact info: John Smith, [email protected], interested in the Pro plan",
}
],
output_format=ContactInfo,
)
# Accédez directement à la sortie analysée
contact = response.parsed_output
print(contact.name, contact.email)Utilitaire transform_schema()
Utile lorsque vous devez transformer manuellement des schémas avant l'envoi, ou lorsque vous souhaitez modifier un schéma généré par Pydantic. Contrairement à client.messages.parse(), qui transforme automatiquement les schémas fournis, cet utilitaire vous donne le schéma transformé afin que vous puissiez le personnaliser davantage.
from anthropic import transform_schema
from pydantic import TypeAdapter
# Convertir d'abord le modèle Pydantic en schéma JSON, puis transformer
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# Modifier le schéma si nécessaire
schema["properties"]["custom_field"] = {"type": "string"}
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "..."}],
output_config={
"format": {"type": "json_schema", "schema": schema},
},
)Les SDK Python, TypeScript, Ruby et PHP transforment automatiquement les schémas comportant 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 :
minimum, maximum, minLength, maxLength)additionalProperties: false à tous les objetsCela 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 « Must be at least 100 » et valide la réponse par rapport à la contrainte d'origine.
Pour appliquer la conformité JSON Schema sur les entrées d'outils avec un échantillonnage contraint par grammaire, consultez Utilisation d'outils stricte.
Les sorties JSON et l'utilisation d'outils stricte résolvent des problèmes différents et fonctionnent ensemble :
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-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'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)Les sorties structurées utilisent un échantillonnage contraint avec des artefacts de grammaire compilés. Cela introduit certaines caractéristiques de performance à connaître :
name ou description n'invalide pas le cacheLors 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 :
output_config.format invalidera toute mise en cache des prompts pour ce fil de conversationLes sorties structurées prennent en charge JSON Schema standard avec certaines limitations. Les sorties JSON et l'utilisation d'outils stricte partagent ces limitations.
Lors de l'utilisation des sorties structurées, les propriétés dans les 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 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 suit :
name (obligatoire, dans l'ordre du schéma)email (obligatoire, dans l'ordre du schéma)notes (optionnel, dans l'ordre du schéma)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 ce réordonnancement dans votre logique d'analyse.
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é :
stop_reason: "refusal"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 :
stop_reason: "max_tokens"max_tokens plus élevée pour obtenir la sortie structurée complèteCasse des valeurs enum
Les sorties structurées ne garantissent pas la capitalisation des valeurs enum et const de type chaîne : Claude peut renvoyer une valeur qui diffère de votre schéma uniquement par la capitalisation, généralement sur la première lettre d'un mot suivant un espace. Par exemple, étant donné ce schéma :
{
"type": "string",
"enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}La sortie peut contenir "Conversation Topic 3" (« T » majuscule) même si cette valeur exacte n'est pas dans l'enum. La réponse se termine normalement, sans erreur ni stop_reason spécial. Cela s'applique à la fois aux sorties JSON et à l'utilisation d'outils stricte. Comparez les valeurs enum sans tenir compte de la casse, et évitez les valeurs enum qui ne diffèrent que par la capitalisation.
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 qui prennent plus de temps à compiler. Pour se protéger contre des temps de compilation excessifs, l'API applique plusieurs limites de complexité.
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 maximum d'outils avec strict: true. Les outils non stricts ne comptent pas dans cette limite. |
| Paramètres optionnels | 24 | Total des paramètres optionnels sur l'ensemble des schémas d'outils stricts et des 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"]) sur l'ensemble des schémas stricts. Ceux-ci sont particulièrement coûteux car ils créent un coût de compilation exponentiel. |
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ère à 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 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 volumineuses peuvent atteindre ce délai d'expiration.
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 cette option aux outils où les violations de schéma causent de réels problèmes, et comptez sur l'adhérence naturelle de Claude pour les outils plus simples.
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.
Simplifiez les structures imbriquées. Les objets profondément imbriqués avec des champs optionnels amplifient la complexité. Aplatissez les structures lorsque c'est possible.
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.
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 après 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 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 l'ensemble des fonctionnalités, consultez API et conservation des données.
Compatible avec :
output_config.format) et l'utilisation d'outils stricte (strict: true) ensemble dans la même requêteIncompatible avec :
output_config.format.Faites en sorte que Claude cite ses sources lorsqu'il répond à des questions sur des documents fournis.
Appliquez 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ù les outils s'exécutent et comment fonctionne la boucle agentique.
Découvrez la structure tarifaire d'Anthropic pour les modèles et les fonctionnalités.
| Supported models |
|
|---|---|
| Supported platforms |
Was this page helpful?