Obtenir une sortie structurée des agents

Les sorties structurées vous permettent de définir la forme exacte des données que vous souhaitez récupérer d'un agent. L'agent peut utiliser tous les outils dont il a besoin pour accomplir la tâche, et vous obtenez toujours du JSON validé correspondant à votre schéma à la fin. Définissez un JSON Schema pour la structure dont vous avez besoin, et le SDK garantit que la sortie correspond.

Pour une sécurité de type complète, utilisez Zod (TypeScript) ou Pydantic (Python) pour définir votre schéma et obtenir des objets fortement typés en retour.

Pourquoi les sorties structurées ?

Les agents retournent du texte libre par défaut, ce qui fonctionne pour le chat mais pas quand vous avez besoin d'utiliser la sortie par programmation. Les sorties structurées vous donnent des données typées que vous pouvez passer directement à votre logique d'application, base de données ou composants UI.

Considérez une application de recettes où un agent recherche sur le web et récupère des recettes. Sans sorties structurées, vous obtenez du texte libre que vous devriez analyser vous-même. Avec les sorties structurées, vous définissez la forme que vous souhaitez et obtenez des données typées que vous pouvez utiliser directement dans votre application.

Démarrage rapide

Pour utiliser les sorties structurées, définissez un JSON Schema décrivant la forme des données que vous souhaitez, puis passez-le à query() via l'option outputFormat (TypeScript) ou output_format (Python). Quand l'agent termine, le message de résultat inclut un champ structured_output avec des données validées correspondant à votre schéma.

L'exemple ci-dessous demande à l'agent de rechercher Anthropic et de retourner le nom de l'entreprise, l'année de fondation et le siège social en tant que sortie structurée.

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

// Définir la forme des données que vous souhaitez récupérer
const schema = {
  type: 'object',
  properties: {
    company_name: { type: 'string' },
    founded_year: { type: 'number' },
    headquarters: { type: 'string' }
  },
  required: ['company_name']
}

for await (const message of query({
  prompt: 'Research Anthropic and provide key company information',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  // Le message de résultat contient structured_output avec des données validées
  if (message.type === 'result' && message.structured_output) {
    console.log(message.structured_output)
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

Schémas type-safe avec Zod et Pydantic

Au lieu d'écrire JSON Schema à la main, vous pouvez utiliser Zod (TypeScript) ou Pydantic (Python) pour définir votre schéma. Ces bibliothèques génèrent le JSON Schema pour vous et vous permettent d'analyser la réponse dans un objet entièrement typé que vous pouvez utiliser dans tout votre codebase avec l'autocomplétion et la vérification de type.

L'exemple ci-dessous définit un schéma pour un plan d'implémentation de fonctionnalité avec un résumé, une liste d'étapes (chacune avec un niveau de complexité) et des risques potentiels. L'agent planifie la fonctionnalité et retourne un objet FeaturePlan typé. Vous pouvez ensuite accéder à des propriétés comme plan.summary et itérer sur plan.steps avec une sécurité de type complète.

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

// Définir le schéma avec Zod
const FeaturePlan = z.object({
  feature_name: z.string(),
  summary: z.string(),
  steps: z.array(z.object({
    step_number: z.number(),
    description: z.string(),
    estimated_complexity: z.enum(['low', 'medium', 'high'])
  })),
  risks: z.array(z.string())
})

type FeaturePlan = z.infer<typeof FeaturePlan>

// Convertir en JSON Schema
const schema = z.toJSONSchema(FeaturePlan)

// Utiliser dans la requête
for await (const message of query({
  prompt: 'Plan how to add dark mode support to a React app. Break it into implementation steps.',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
})) {
  if (message.type === 'result' && message.structured_output) {
    // Valider et obtenir le résultat entièrement typé
    const parsed = FeaturePlan.safeParse(message.structured_output)
    if (parsed.success) {
      const plan: FeaturePlan = parsed.data
      console.log(`Feature: ${plan.feature_name}`)
      console.log(`Summary: ${plan.summary}`)
      plan.steps.forEach(step => {
        console.log(`${step.step_number}. [${step.estimated_complexity}] ${step.description}`)
      })
    }
  }
}

Avantages :

• Inférence de type complète (TypeScript) et indices de type (Python)
• Validation à l'exécution avec safeParse() ou model_validate()
• Meilleurs messages d'erreur
• Schémas composables et réutilisables

Configuration du format de sortie

L'option outputFormat (TypeScript) ou output_format (Python) accepte un objet avec :

• type : Défini sur "json_schema" pour les sorties structurées
• schema : Un objet JSON Schema définissant votre structure de sortie. Vous pouvez générer ceci à partir d'un schéma Zod avec z.toJSONSchema() ou d'un modèle Pydantic avec .model_json_schema()

Le SDK supporte les fonctionnalités JSON Schema standard incluant tous les types de base (object, array, string, number, boolean, null), enum, const, required, les objets imbriqués et les définitions $ref. Pour la liste complète des fonctionnalités supportées et des limitations, voir Limitations JSON Schema.

Exemple : agent de suivi TODO

Cet exemple démontre comment les sorties structurées fonctionnent avec l'utilisation multi-étapes d'outils. L'agent doit trouver des commentaires TODO dans la base de code, puis rechercher les informations de git blame pour chacun. Il décide de manière autonome quels outils utiliser (Grep pour rechercher, Bash pour exécuter les commandes git) et combine les résultats dans une seule réponse structurée.

Le schéma inclut des champs optionnels (author et date) puisque les informations de git blame pourraient ne pas être disponibles pour tous les fichiers. L'agent remplit ce qu'il peut trouver et omet le reste.

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

// Définir la structure pour l'extraction TODO
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']
}

// L'agent utilise Grep pour trouver les TODOs, Bash pour obtenir les informations de git blame
for await (const message of query({
  prompt: 'Find all TODO comments in this codebase 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}`)
      }
    })
  }
}

Gestion des erreurs

La génération de sortie structurée peut échouer quand l'agent ne peut pas produire du JSON valide correspondant à votre schéma. Cela se produit généralement quand le schéma est trop complexe pour la tâche, la tâche elle-même est ambiguë, ou l'agent atteint sa limite de tentatives en essayant de corriger les erreurs de validation.

Quand une erreur se produit, le message de résultat a un subtype indiquant ce qui s'est mal passé :

L'exemple ci-dessous vérifie le champ subtype pour déterminer si la sortie a été générée avec succès ou si vous devez gérer un échec :

for await (const msg of query({
  prompt: 'Extract contact info from the document',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: contactSchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      // Utiliser la sortie validée
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      // Gérer l'échec - réessayer avec une invite plus simple, revenir à non-structuré, etc.
      console.error('Could not produce valid output')
    }
  }
}

Conseils pour éviter les erreurs :

• Gardez les schémas ciblés. Les schémas profondément imbriqués avec de nombreux champs requis sont plus difficiles à satisfaire. Commencez simple et ajoutez de la complexité au besoin.
• Faites correspondre le schéma à la tâche. Si la tâche pourrait ne pas avoir toutes les informations que votre schéma requiert, rendez ces champs optionnels.
• Utilisez des invites claires. Les invites ambiguës rendent plus difficile pour l'agent de savoir quelle sortie produire.

Ressources connexes

• Documentation JSON Schema : apprenez la syntaxe JSON Schema pour définir des schémas complexes avec des objets imbriqués, des tableaux, des énumérations et des contraintes de validation
• Sorties structurées API : utilisez les sorties structurées avec l'API Claude directement pour les requêtes single-turn sans utilisation d'outils
• Outils personnalisés : donnez à votre agent des outils personnalisés à appeler pendant l'exécution avant de retourner une sortie structurée