Sorties structurées dans le SDK

Obtenez du JSON structuré et validé à partir de workflows d'agents. Le SDK Agent prend en charge les sorties structurées via des schémas JSON, garantissant que vos agents retournent des données exactement au format dont vous avez besoin.

Quand utiliser les sorties structurées

Utilisez les sorties structurées lorsque vous avez besoin de JSON validé après qu'un agent ait complété un workflow multi-tour avec des outils (recherches de fichiers, exécution de commandes, recherche web, etc.).

Pour les appels API uniques sans utilisation d'outils, voir Sorties structurées API.

Pourquoi utiliser les sorties structurées

Les sorties structurées offrent une intégration fiable et type-safe avec vos applications :

Structure validée : Recevez toujours du JSON valide correspondant à votre schéma
Intégration simplifiée : Aucun code d'analyse ou de validation nécessaire
Sécurité des types : Utilisez avec les indices de type TypeScript ou Python pour une sécurité de bout en bout
Séparation claire : Définissez les exigences de sortie séparément des instructions de tâche
Autonomie des outils : L'agent choisit les outils à utiliser tout en garantissant le format de sortie

Comment fonctionnent les sorties structurées

Définir votre schéma JSON
Créez un schéma JSON qui décrit la structure que vous voulez que l'agent retourne. Le schéma utilise le format standard JSON Schema.
Ajouter le paramètre outputFormat
Incluez le paramètre outputFormat dans vos options de requête avec type: "json_schema" et votre définition de schéma.
Exécuter votre requête
L'agent utilise tous les outils dont il a besoin pour compléter la tâche (opérations sur fichiers, commandes, recherche web, etc.).
Accéder à la sortie validée
Le résultat final de l'agent sera du JSON valide correspondant à votre schéma, disponible dans message.structured_output.

Fonctionnalités JSON Schema prises en charge

Le SDK Agent prend en charge les mêmes fonctionnalités et limitations de JSON Schema que Sorties structurées API.

Fonctionnalités clés prises en charge :

Tous les types de base : object, array, string, integer, number, boolean, null
enum, const, required, additionalProperties (doit être false)
Formats de chaîne : date-time, date, email, uri, uuid, etc.
$ref, $def, et definitions

Pour des détails complets sur les fonctionnalités prises en charge, les limitations et le support des motifs regex, voir Limitations JSON Schema dans la documentation de l'API.

Exemple : Agent de suivi des TODOs

Voici un exemple complet montrant un agent qui recherche des TODOs dans le code et extrait les informations de git blame :

L'agent utilise de manière autonome les bons outils (Grep, Bash) pour rassembler les informations et retourne des données validées.

Gestion des erreurs

Si l'agent ne peut pas produire une sortie valide correspondant à votre schéma, vous recevrez un résultat d'erreur :

for await (const msg of query({
  prompt: 'Analyze the data',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: mySchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      console.error('Could not produce valid output')
    }
  }
}

Ressources connexes

Documentation JSON Schema
Sorties structurées API - Pour les appels API uniques
Outils personnalisés - Définir des outils pour vos agents
Référence SDK TypeScript - API TypeScript complète
Référence SDK Python - API Python complète

import { query } from '@anthropic-ai/claude-agent-sdk'

// Define structure for TODO extraction
const todoSchema = {
  type: 'object',
  properties: {
    todos: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          text: { type: 'string' },
          file: { type: 'string' },
          line: { type: 'number' },
          author: { type: 'string' },
          date: { type: 'string' }
        },
        required: ['text', 'file', 'line']
      }
    },
    total_count: { type: 'number' }
  },
  required: ['todos', 'total_count']
}

// Agent uses Grep to find TODOs, Bash to get git blame info
for await (const message of query({
  prompt: 'Find all TODO comments in src/ and identify who added them',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: todoSchema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    const data = message.structured_output
    console.log(`Found ${data.total_count} TODOs`)
    data.todos.forEach(todo => {
      console.log(`${todo.file}:${todo.line} - ${todo.text}`)
      if (todo.author) {
        console.log(`  Added by ${todo.author} on ${todo.date}`)
      }
    })
  }
}