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.

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

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 :

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}`)
      }
    })
  }
}

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