Output strutturati

Gli output strutturati vincolano le risposte di Claude a seguire uno schema specifico, garantendo un 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): 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 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 validi: Niente più errori JSON.parse()
• Type safe: Tipi di campo garantiti e campi obbligatori
• Affidabili: Nessun nuovo tentativo necessario per violazioni dello schema

Output JSON

Gli output JSON controllano il formato della risposta di Claude, garantendo che Claude restituisca JSON valido che corrisponda 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 che corrisponde 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.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 vuoi modificare uno schema generato da Pydantic. A differenza di client.messages.parse(), che trasforma automaticamente gli schemi forniti, questo ti dà lo schema trasformato in modo che tu possa personalizzarlo 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, garantendo 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 degli agenti
• Garantire chiamate di funzione type-safe
• Gestire strumenti complessi con proprietà nidificate

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

La costruzione di sistemi di agenti affidabili richiede la conformità dello schema garantita. 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 (da strumenti forniti o 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)

Se combinati, Claude può chiamare strumenti con parametri garantiti validi E restituire risposte JSON strutturate. Questo è utile per i flussi di lavoro degli agenti 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 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_config.format invaliderà qualsiasi prompt cache 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

Mentre gli output strutturati garantiscono 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 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 output strutturati su larga scala con sconto del 50%
• Conteggio dei token: Conta i token senza compilazione
• Streaming: Trasmetti output strutturati come risposte normali
• Utilizzo combinato: Utilizza output JSON (output_config.format) e uso rigoroso degli strumenti (strict: true) insieme nella stessa richiesta

Incompatibile con:

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