Ottenere output strutturato dagli agenti

Gli output strutturati ti permettono di definire la forma esatta dei dati che desideri ricevere da un agente. L'agente può utilizzare qualsiasi strumento di cui ha bisogno per completare l'attività, e riceverai comunque JSON convalidato corrispondente al tuo schema alla fine. Definisci uno JSON Schema per la struttura di cui hai bisogno, e l'SDK garantisce che l'output corrisponda ad esso.

Per la massima type safety, utilizza Zod (TypeScript) o Pydantic (Python) per definire il tuo schema e ottenere oggetti fortemente tipizzati.

Perché gli output strutturati?

Gli agenti restituiscono testo libero per impostazione predefinita, il che funziona per la chat ma non quando hai bisogno di utilizzare l'output a livello di programmazione. Gli output strutturati ti danno dati tipizzati che puoi passare direttamente alla logica della tua applicazione, al database o ai componenti UI.

Considera un'app di ricette in cui un agente cerca sul web e recupera ricette. Senza output strutturati, ottieni testo libero che dovresti analizzare tu stesso. Con output strutturati, definisci la forma che desideri e ottieni dati tipizzati che puoi utilizzare direttamente nella tua app.

Avvio rapido

Per utilizzare gli output strutturati, definisci uno JSON Schema che descrive la forma dei dati che desideri, quindi passalo a query() tramite l'opzione outputFormat (TypeScript) o output_format (Python). Quando l'agente termina, il messaggio di risultato include un campo structured_output con dati convalidati corrispondenti al tuo schema.

L'esempio seguente chiede all'agente di ricercare Anthropic e restituire il nome dell'azienda, l'anno di fondazione e la sede come output strutturato.

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

// Definisci la forma dei dati che desideri ricevere
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
    }
  }
})) {
  // Il messaggio di risultato contiene structured_output con dati convalidati
  if (message.type === 'result' && message.structured_output) {
    console.log(message.structured_output)
    // { company_name: "Anthropic", founded_year: 2021, headquarters: "San Francisco, CA" }
  }
}

Schema type-safe con Zod e Pydantic

Invece di scrivere JSON Schema a mano, puoi utilizzare Zod (TypeScript) o Pydantic (Python) per definire il tuo schema. Queste librerie generano lo JSON Schema per te e ti permettono di analizzare la risposta in un oggetto completamente tipizzato che puoi utilizzare in tutto il tuo codebase con autocomplete e type checking.

L'esempio seguente definisce uno schema per un piano di implementazione di funzionalità con un riepilogo, un elenco di passaggi (ciascuno con livello di complessità) e rischi potenziali. L'agente pianifica la funzionalità e restituisce un oggetto FeaturePlan tipizzato. Puoi quindi accedere a proprietà come plan.summary e iterare su plan.steps con completa type safety.

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

// Definisci lo schema con 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>

// Converti in JSON Schema
const schema = z.toJSONSchema(FeaturePlan)

// Utilizza nella query
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) {
    // Valida e ottieni il risultato completamente tipizzato
    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}`)
      })
    }
  }
}

Vantaggi:

• Inferenza di tipo completa (TypeScript) e type hints (Python)
• Validazione a runtime con safeParse() o model_validate()
• Messaggi di errore migliori
• Schema componibili e riutilizzabili

Configurazione del formato di output

L'opzione outputFormat (TypeScript) o output_format (Python) accetta un oggetto con:

• type: Impostato su "json_schema" per gli output strutturati
• schema: Un oggetto JSON Schema che definisce la struttura del tuo output. Puoi generarlo da uno schema Zod con z.toJSONSchema() o da un modello Pydantic con .model_json_schema()

L'SDK supporta le funzionalità standard di JSON Schema inclusi tutti i tipi di base (object, array, string, number, boolean, null), enum, const, required, oggetti annidati e definizioni $ref. Per l'elenco completo delle funzionalità supportate e delle limitazioni, vedi Limitazioni di JSON Schema.

Esempio: agente di tracciamento TODO

Questo esempio dimostra come funzionano gli output strutturati con l'uso di strumenti multi-step. L'agente deve trovare commenti TODO nel codebase, quindi cercare le informazioni di git blame per ciascuno. Decide autonomamente quali strumenti utilizzare (Grep per la ricerca, Bash per eseguire comandi git) e combina i risultati in una singola risposta strutturata.

Lo schema include campi opzionali (author e date) poiché le informazioni di git blame potrebbero non essere disponibili per tutti i file. L'agente riempie quello che riesce a trovare e omette il resto.

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

// Definisci la struttura per l'estrazione di 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'agente utilizza Grep per trovare TODO, Bash per ottenere informazioni di 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}`)
      }
    })
  }
}

Gestione degli errori

La generazione di output strutturato può fallire quando l'agente non riesce a produrre JSON valido corrispondente al tuo schema. Questo accade tipicamente quando lo schema è troppo complesso per l'attività, l'attività stessa è ambigua, o l'agente raggiunge il limite di tentativi cercando di correggere gli errori di validazione.

Quando si verifica un errore, il messaggio di risultato ha un subtype che indica cosa è andato storto:

L'esempio seguente controlla il campo subtype per determinare se l'output è stato generato con successo o se hai bisogno di gestire un errore:

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) {
      // Utilizza l'output convalidato
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      // Gestisci l'errore - riprova con un prompt più semplice, ricadi su non strutturato, ecc.
      console.error('Could not produce valid output')
    }
  }
}

Suggerimenti per evitare errori:

• Mantieni gli schema focalizzati. Gli schema profondamente annidati con molti campi obbligatori sono più difficili da soddisfare. Inizia semplice e aggiungi complessità secondo le necessità.
• Abbina lo schema all'attività. Se l'attività potrebbe non avere tutte le informazioni che il tuo schema richiede, rendi quei campi opzionali.
• Utilizza prompt chiari. I prompt ambigui rendono più difficile per l'agente sapere quale output produrre.

Risorse correlate

• Documentazione di JSON Schema: impara la sintassi di JSON Schema per definire schema complessi con oggetti annidati, array, enum e vincoli di validazione
• API Structured Outputs: utilizza gli output strutturati direttamente con l'API Claude per richieste single-turn senza uso di strumenti
• Strumenti personalizzati: fornisci al tuo agente strumenti personalizzati da chiamare durante l'esecuzione prima di restituire l'output strutturato