Output strutturati

Gli output strutturati vincolano le risposte di Claude a seguire uno schema specifico, garantendo output valido e analizzabile per l'elaborazione a valle. Sono disponibili due funzionalità complementari:

• Output JSON (output_config.format): Ottieni la risposta di Claude in un formato JSON specifico
• Uso rigoroso degli strumenti (strict: true): Garantisce la validazione dello schema sui nomi degli strumenti e sugli input

Queste funzionalità possono essere utilizzate indipendentemente o insieme nella stessa richiesta.

Perché usare gli output strutturati

Senza output strutturati, Claude può generare risposte JSON malformate o input di strumenti non validi che interrompono le tue applicazioni. Anche con un'attenta impostazione dei prompt, potresti incontrare:

• Errori di analisi da sintassi JSON non valida
• Campi obbligatori mancanti
• Tipi di dati incoerenti
• Violazioni dello schema che richiedono gestione degli errori e nuovi tentativi

Gli output strutturati garantiscono risposte conformi allo schema tramite decodifica vincolata:

• Sempre validi: Niente più errori JSON.parse()
• Type safe: Tipi di campo e campi obbligatori garantiti
• Affidabili: Nessun nuovo tentativo necessario per le violazioni dello schema

Output JSON

Gli output JSON controllano il formato di risposta di Claude, garantendo che Claude restituisca JSON valido corrispondente al tuo schema. Usa gli output JSON quando hai bisogno di:

• Controllare il formato di risposta di Claude
• Estrarre dati da immagini o testo
• Generare report strutturati
• Formattare le risposte API

Avvio rapido

Formato della risposta: JSON valido corrispondente al tuo schema in response.content[0].text

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

Come funziona

Lavorare con gli output JSON negli SDK

Gli SDK forniscono helper che semplificano il lavoro con gli output JSON, inclusa la trasformazione degli schemi, la validazione automatica e l'integrazione con le librerie di schemi più diffuse.

Utilizzo delle definizioni di schema native

Invece di scrivere schemi JSON grezzi, puoi utilizzare strumenti di definizione degli schemi familiari nel tuo linguaggio:

• Python: modelli Pydantic con client.messages.parse()
• TypeScript: schemi Zod con zodOutputFormat()
• Java: classi Java semplici con derivazione automatica dello schema tramite outputFormat(Class<T>)
• Ruby: classi Anthropic::BaseModel con output_config: {format: Model}
• C#, Go, PHP: schemi JSON grezzi passati tramite output_config

Metodi specifici per SDK

Ogni SDK fornisce helper che semplificano il lavoro con gli output strutturati. Consulta le singole pagine degli SDK per i dettagli completi.

Come funziona la trasformazione dell'SDK

Gli SDK Python e TypeScript trasformano automaticamente gli schemi con funzionalità non supportate:

1. Rimozione dei vincoli non supportati (ad es., minimum, maximum, minLength, maxLength)
2. Aggiornamento delle descrizioni con le informazioni sui vincoli (ad es., "Deve essere almeno 100"), quando il vincolo non è direttamente supportato con gli output strutturati
3. Aggiunta di additionalProperties: false a tutti gli oggetti
4. Filtraggio dei formati stringa solo all'elenco supportato
5. Validazione delle risposte rispetto allo schema originale (con tutti i vincoli)

Ciò significa che Claude riceve uno schema semplificato, ma il tuo codice applica comunque tutti i vincoli tramite la validazione.

Esempio: Un campo Pydantic con minimum: 100 diventa un intero semplice nello schema inviato, ma la descrizione viene aggiornata a "Deve essere almeno 100" e l'SDK valida la risposta rispetto al vincolo originale.

Casi d'uso comuni

Utilizzo rigoroso degli strumenti

L'utilizzo rigoroso degli strumenti valida i parametri degli strumenti, garantendo che Claude chiami le tue funzioni con argomenti correttamente tipizzati. Usa l'utilizzo rigoroso degli strumenti quando hai bisogno di:

• Validare i parametri degli strumenti
• Costruire flussi di lavoro agentici
• Garantire chiamate di funzione type-safe
• Gestire strumenti complessi con proprietà annidate

Perché l'utilizzo rigoroso degli strumenti è importante per gli agenti

La costruzione di sistemi agentici affidabili richiede la conformità garantita allo schema. Senza la modalità strict, Claude potrebbe restituire tipi incompatibili ("2" invece di 2) o campi obbligatori mancanti, rompendo le tue funzioni e causando errori di runtime.

L'utilizzo rigoroso degli strumenti garantisce parametri type-safe:

• Le funzioni ricevono argomenti correttamente tipizzati ogni volta
• Nessuna necessità di validare e riprovare le chiamate agli strumenti
• Agenti pronti per la produzione che funzionano in modo coerente su larga scala

Ad esempio, supponiamo che un sistema di prenotazione abbia bisogno di passengers: int. Senza la modalità strict, Claude potrebbe fornire passengers: "two" o passengers: "2". Con strict: true, la risposta conterrà sempre passengers: 2.

Avvio rapido

Formato della risposta: Blocchi di utilizzo degli strumenti con input validati in response.content[x].input

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Garanzie:

• L'input dello strumento segue rigorosamente l'input_schema
• Il name dello strumento è sempre valido (dagli strumenti forniti o dagli strumenti del server)

Come funziona

Casi d'uso comuni

Utilizzo di entrambe le funzionalità insieme

Gli output JSON e l'uso strict degli strumenti risolvono problemi diversi e possono essere utilizzati insieme:

• Output JSON controllano il formato della risposta di Claude (cosa dice Claude)
• Uso strict degli strumenti valida i parametri degli strumenti (come Claude chiama le tue funzioni)

Quando combinati, Claude può chiamare gli strumenti con parametri garantiti validi E restituire risposte JSON strutturate. Questo è utile per i flussi di lavoro agentivi in cui hai bisogno sia di chiamate agli strumenti affidabili che di output finali strutturati.

Considerazioni importanti

Compilazione della grammatica e caching

Gli output strutturati utilizzano il campionamento vincolato con artefatti di grammatica compilati. Questo introduce alcune caratteristiche di prestazione di cui essere consapevoli:

• Latenza della prima richiesta: La prima volta che utilizzi uno schema specifico, ci sarà una latenza aggiuntiva mentre la grammatica viene compilata
• Caching automatico: Le grammatiche compilate vengono memorizzate nella cache per 24 ore dall'ultimo utilizzo, rendendo le richieste successive molto più veloci
• Invalidazione della cache: La cache viene invalidata se modifichi:
  • La struttura dello schema JSON
  • L'insieme degli strumenti nella tua richiesta (quando si utilizzano sia gli output strutturati che l'uso degli strumenti)
  • Modificare solo i campi name o description non invalida la cache

Modifica del prompt e costi dei token

Quando si utilizzano gli output strutturati, Claude riceve automaticamente un prompt di sistema aggiuntivo che spiega il formato di output atteso. Ciò significa:

• Il conteggio dei token di input sarà leggermente più alto
• Il prompt iniettato ti costa token come qualsiasi altro prompt di sistema
• La modifica del parametro output_config.format invaliderà qualsiasi cache del prompt per quel thread di conversazione

Limitazioni dello schema JSON

Gli output strutturati supportano lo schema JSON standard con alcune limitazioni. Sia gli output JSON che l'uso strict degli strumenti condividono queste limitazioni.

Ordinamento delle proprietà

Quando si utilizzano gli output strutturati, le proprietà negli oggetti mantengono il loro ordine definito dallo schema, con un'importante avvertenza: le proprietà obbligatorie appaiono prima, seguite dalle proprietà opzionali.

Ad esempio, dato questo schema:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

L'output ordinerà le proprietà come:

1. name (obbligatorio, nell'ordine dello schema)
2. email (obbligatorio, nell'ordine dello schema)
3. notes (opzionale, nell'ordine dello schema)
4. age (opzionale, nell'ordine dello schema)

Ciò significa che l'output potrebbe apparire come:

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Se l'ordine delle proprietà nell'output è importante per la tua applicazione, assicurati che tutte le proprietà siano contrassegnate come obbligatorie, oppure tieni conto di questo riordinamento nella tua logica di analisi.

Output non validi

Sebbene gli output strutturati garantiscano la conformità allo schema nella maggior parte dei casi, esistono scenari in cui l'output potrebbe non corrispondere al tuo schema:

Rifiuti (stop_reason: "refusal")

Claude mantiene le sue proprietà di sicurezza e utilità anche quando utilizza gli output strutturati. Se Claude rifiuta una richiesta per motivi di sicurezza:

• La risposta avrà stop_reason: "refusal"
• Riceverai un codice di stato 200
• Ti verranno addebitati i token generati
• L'output potrebbe non corrispondere al tuo schema perché il messaggio di rifiuto ha la precedenza sui vincoli dello schema

Limite di token raggiunto (stop_reason: "max_tokens")

Se la risposta viene interrotta a causa del raggiungimento del limite max_tokens:

• La risposta avrà stop_reason: "max_tokens"
• L'output potrebbe essere incompleto e non corrispondere al tuo schema
• Riprova con un valore max_tokens più alto per ottenere l'output strutturato completo

Limiti di complessità dello schema

Gli output strutturati funzionano compilando i tuoi schemi JSON in una grammatica che vincola l'output di Claude. Gli schemi più complessi producono grammatiche più grandi che richiedono più tempo per essere compilate. Per proteggersi da tempi di compilazione eccessivi, l'API applica diversi limiti di complessità.

Limiti espliciti

I seguenti limiti si applicano a tutte le richieste con output_config.format o strict: true:

Limiti interni aggiuntivi

Oltre ai limiti espliciti sopra indicati, esistono limiti interni aggiuntivi sulla dimensione della grammatica compilata. Questi limiti esistono perché la complessità dello schema non si riduce a una singola dimensione: funzionalità come parametri opzionali, tipi unione, oggetti annidati e numero di strumenti interagiscono tra loro in modi che possono rendere la grammatica compilata sproporzionatamente grande.

Quando questi limiti vengono superati, riceverai un errore 400 con il messaggio "Schema is too complex for compilation." Questi errori significano che la complessità combinata dei tuoi schemi supera ciò che può essere compilato in modo efficiente, anche se ogni singolo limite sopra indicato è soddisfatto. Come ultima misura di sicurezza, l'API applica anche un timeout di compilazione di 180 secondi. Gli schemi che superano tutti i controlli espliciti ma producono grammatiche compilate molto grandi potrebbero raggiungere questo timeout.

Suggerimenti per ridurre la complessità dello schema

Se stai raggiungendo i limiti di complessità, prova queste strategie nell'ordine indicato:

1. Contrassegna solo gli strumenti critici come strict. Se hai molti strumenti, riservalo agli strumenti in cui le violazioni dello schema causano problemi reali, e affidati all'aderenza naturale di Claude per gli strumenti più semplici.

2. Riduci i parametri opzionali. Rendi i parametri required dove possibile. Ogni parametro opzionale raddoppia approssimativamente una porzione dello spazio degli stati della grammatica. Se un parametro ha sempre un valore predefinito ragionevole, considera di renderlo obbligatorio e di far fornire esplicitamente quel valore predefinito a Claude.

3. Semplifica le strutture annidate. Gli oggetti profondamente annidati con campi opzionali aumentano la complessità. Appiattisci le strutture dove possibile.

4. Dividi in più richieste. Se hai molti strumenti strict, considera di distribuirli su richieste separate o sotto-agenti.

Per problemi persistenti con schemi validi, contatta il supporto con la definizione del tuo schema.

Conservazione dei dati

I prompt e le risposte vengono elaborati con ZDR quando si utilizzano gli output strutturati. Tuttavia, lo schema JSON stesso viene temporaneamente memorizzato nella cache per un massimo di 24 ore dall'ultimo utilizzo per scopi di ottimizzazione. Nessun dato di prompt o risposta viene conservato oltre la risposta API.

Per l'idoneità ZDR in tutte le funzionalità, consulta API e conservazione dei dati.

Compatibilità delle funzionalità

Funziona con:

• Elaborazione batch: Elabora gli output strutturati su larga scala con uno sconto del 50%
• Conteggio dei token: Conta i token senza compilazione
• Streaming: Trasmetti gli output strutturati come risposte normali
• Utilizzo combinato: Usa gli output JSON (output_config.format) e l'uso strict degli strumenti (strict: true) insieme nella stessa richiesta

Incompatibile con:

• Citazioni: Le citazioni richiedono l'intercalazione di blocchi di citazione con il testo, il che è in conflitto con i vincoli strict dello schema JSON. Restituisce un errore 400 se le citazioni sono abilitate con output_config.format.
• Prefilling dei messaggi: Incompatibile con gli output JSON