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_format): Ottieni la risposta di Claude in un formato JSON specifico
• Uso rigoroso degli strumenti (strict: true): Garantisci la convalidazione dello schema sui nomi e gli input degli strumenti

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

Perché utilizzare 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 prompt attento, 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 attraverso la decodifica vincolata:

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

Output JSON

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

• Controllare il formato della risposta di Claude
• Estrarre dati da immagini o testo
• Generare report strutturati
• Formattare 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 Python e TypeScript forniscono helper che rendono più facile lavorare con gli output JSON, inclusa la trasformazione dello schema, la convalidazione automatica e l'integrazione con librerie di schema popolari.

Utilizzo di Pydantic e Zod

Per gli sviluppatori Python e TypeScript, puoi utilizzare strumenti familiari di definizione dello schema come Pydantic e Zod invece di scrivere schemi JSON grezzi.

Metodi specifici dell'SDK

Python: client.beta.messages.parse() (Consigliato)

Il metodo parse() trasforma automaticamente il tuo modello Pydantic, convalida la risposta e restituisce un attributo parsed_output.

Python: helper transform_schema()

Per quando hai bisogno di trasformare manualmente gli schemi prima di inviarli, o quando desideri modificare uno schema generato da Pydantic. A differenza di client.beta.messages.parse(), che trasforma automaticamente gli schemi forniti, questo ti fornisce lo schema trasformato in modo da poterlo personalizzare ulteriormente.

Come funziona la trasformazione dell'SDK

Sia gli SDK Python che TypeScript trasformano automaticamente gli schemi con funzionalità non supportate:

1. Rimuovi i vincoli non supportati (ad es. minimum, maximum, minLength, maxLength)
2. Aggiorna le descrizioni con informazioni sui vincoli (ad es. "Deve essere almeno 100"), quando il vincolo non è direttamente supportato con output strutturati
3. Aggiungi additionalProperties: false a tutti gli oggetti
4. Filtra i formati di stringa solo all'elenco supportato
5. Convalida le risposte rispetto al tuo schema originale (con tutti i vincoli)

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

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

Casi d'uso comuni

Uso rigoroso degli strumenti

L'uso rigoroso degli strumenti convalida i parametri dello strumento, assicurando che Claude chiami le tue funzioni con argomenti correttamente tipizzati. Utilizza l'uso rigoroso degli strumenti quando hai bisogno di:

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

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

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

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

• Le funzioni ricevono argomenti correttamente tipizzati ogni volta
• Nessuna necessità di convalidare e riprovare le chiamate dello strumento
• 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à rigorosa, 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 dello strumento con input convalidati 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 rigoroso degli strumenti risolvono problemi diversi e possono essere utilizzati insieme:

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

Quando combinati, Claude può chiamare strumenti con parametri garantiti validi E restituire risposte JSON strutturate. Questo è utile per i flussi di lavoro agentici in cui hai bisogno sia di chiamate di 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 di strumenti nella tua richiesta (quando utilizzi sia output strutturati che uso dello strumento)
  • La modifica solo dei campi name o description non invalida la cache

Modifica del prompt e costi dei token

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

• Il tuo conteggio dei token di input sarà leggermente superiore
• Il prompt iniettato ti costa token come qualsiasi altro prompt di sistema
• La modifica del parametro output_format invaliderà qualsiasi cache del prompt per quel thread di conversazione

Limitazioni JSON Schema

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

Output non validi

Sebbene gli output strutturati garantiscano la conformità dello schema nella maggior parte dei casi, ci sono 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 verrà addebitato per 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

Errori di convalidazione dello schema

Se il tuo schema utilizza funzionalità non supportate o è troppo complesso, riceverai un errore 400:

"Too many recursive definitions in schema"

• Causa: Lo schema ha definizioni ricorsive eccessive o cicliche
• Soluzione: Semplifica la struttura dello schema, riduci la profondità di annidamento

"Schema is too complex"

• Causa: Lo schema supera i limiti di complessità
• Soluzione: Dividi in schemi più piccoli, semplifica la struttura o riduci il numero di strumenti contrassegnati come strict: true

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

Compatibilità delle funzionalità

Funziona con:

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

Incompatibile con:

• Citazioni: Le citazioni richiedono l'interleaving di blocchi di citazioni con testo, il che entra in conflitto con i vincoli rigorosi dello schema JSON. Restituisce errore 400 se le citazioni sono abilitate con output_format.
• Prefill dei messaggi: Incompatibile con gli output JSON