Output strutturati nell'SDK

Ottieni JSON strutturati e convalidati dai flussi di lavoro degli agenti. L'Agent SDK supporta output strutturati attraverso JSON Schemas, assicurando che i tuoi agenti restituiscano dati esattamente nel formato di cui hai bisogno.

Perché utilizzare output strutturati

Gli output strutturati forniscono un'integrazione affidabile e type-safe con le tue applicazioni:

• Struttura convalidata: Ricevi sempre JSON valido corrispondente al tuo schema
• Integrazione semplificata: Non è necessario codice di parsing o validazione
• Type safety: Utilizza con suggerimenti di tipo TypeScript o Python per la sicurezza end-to-end
• Separazione pulita: Definisci i requisiti di output separatamente dalle istruzioni del compito
• Autonomia dello strumento: L'agente sceglie quali strumenti utilizzare garantendo il formato di output

Come funzionano gli output strutturati

Funzionalità JSON Schema supportate

L'Agent SDK supporta le stesse funzionalità e limitazioni di JSON Schema di API Structured Outputs.

Funzionalità chiave supportate:

• Tutti i tipi di base: object, array, string, integer, number, boolean, null
• enum, const, required, additionalProperties (deve essere false)
• Formati di stringa: date-time, date, email, uri, uuid, ecc.
• $ref, $def, e definitions

Per i dettagli completi sulle funzionalità supportate, limitazioni e supporto dei pattern regex, vedi Limitazioni JSON Schema nella documentazione dell'API.

Esempio: agente di tracciamento TODO

Ecco un esempio completo che mostra un agente che cerca TODO nel codice ed estrae informazioni di 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'agente utilizza autonomamente gli strumenti giusti (Grep, Bash) per raccogliere informazioni e restituisce dati convalidati.

Gestione degli errori

Se l'agente non riesce a produrre un output valido corrispondente al tuo schema, riceverai un risultato di errore:

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

Risorse correlate

• Documentazione JSON Schema
• API Structured Outputs - Per singole chiamate API
• Strumenti personalizzati - Definisci strumenti per i tuoi agenti
• Riferimento SDK TypeScript - API TypeScript completa
• Riferimento SDK Python - API Python completa