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) : Obtenir la réponse de Claude dans un format JSON spécifique
• Utilisation stricte d'outils (strict: true) : Garantir 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 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

Sorties JSON

Les sorties JSON contrôlent le format de réponse de Claude, garantissant que Claude retourne un JSON valide correspondant à votre schéma. Utilisez les sorties JSON quand 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 les réponses d'API

Démarrage rapide

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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
        }
      }
    }
  }'

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

Utiliser 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.

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.messages.create(
    model="claude-opus-4-6",
    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": transform_schema(ContactInfo),
        }
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.messages.parse(
    model="claude-opus-4-6",
    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 au SDK

Python : client.messages.parse() (Recommandé)

La méthode parse() transforme automatiquement votre modèle Pydantic, valide la réponse et retourne un attribut parsed_output.

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.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 :

1. Supprimer les contraintes non supportées (par exemple, minimum, maximum, minLength, maxLength)
2. Mettre à 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
3. Ajouter additionalProperties: false à tous les objets
4. Filtrer les formats de chaîne à la liste supportée uniquement
5. Valider les 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 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 originale.

Cas d'usage courants

Utilisation stricte d'outils

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

• Valider les paramètres d'outils
• Construire des flux de travail d'agent
• Assurer les appels de fonction type-safe
• Gérer les outils complexes avec des propriétés imbriquées

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

La construction de systèmes d'agent fiables nécessite une conformité garantie au schéma. Sans le mode strict, Claude pourrait retourner des types incompatibles ("2" au lieu de 2) ou des champs obligatoires manquants, cassant vos fonctions et 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, la réponse contiendra toujours passengers: 2.

Démarrage rapide

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }]
  }'

Format de réponse : Blocs d'utilisation d'outils avec 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 (à partir des outils fournis ou des outils serveur)

Comment ça fonctionne

Cas d'usage courants

Utiliser les deux fonctionnalités ensemble

Les sorties JSON et l'utilisation stricte d'outils résolvent des problèmes différents et peuvent être utilisées ensemble :

• Sorties JSON contrôlent le format de réponse de Claude (ce que Claude dit)
• Utilisation stricte d'outils valide les paramètres d'outils (comment Claude appelle vos fonctions)

Quand combinées, Claude peut appeler des outils avec des paramètres garantis valides ET retourner des réponses JSON structurées. Ceci est utile pour les flux de travail d'agent 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-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Help me plan a trip to Paris for next month"}],
    # JSON outputs: structured response format
    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
            }
        }
    },
    # Strict tool use: guaranteed tool parameters
    tools=[{
        "name": "search_flights",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "destination": {"type": "string"},
                "date": {"type": "string", "format": "date"}
            },
            "required": ["destination", "date"],
            "additionalProperties": False
        }
    }]
)

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 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, rendant les requêtes suivantes beaucoup plus rapides
• Invalidation du cache : Le cache est invalidé si vous changez :
  • 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_config.format invalidera tout cache d'invite 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 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 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 car le message de refus prend la priorité sur les contraintes de schéma

Limite de jetons atteinte (stop_reason: "max_tokens")

Si la réponse est coupée en raison du dépassement 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 : Simplifier la structure du schéma, réduire la profondeur d'imbrication

« Le schéma est trop complexe »

• Cause : Le schéma dépasse les limites de complexité
• Solution : Diviser en schémas plus petits, simplifier la structure ou réduire 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 lot : Traiter les sorties structurées à l'échelle avec une réduction de 50 %
• Comptage de jetons : Compter les jetons sans compilation
• Streaming : Diffuser les sorties structurées comme les réponses normales
• Utilisation combinée : Utiliser 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 les 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_config.format.
• Préfixage de message : Incompatible avec les sorties JSON