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. Usa output JSON (output_format) per risposte di dati strutturati, o uso rigoroso degli strumenti (strict: true) per la validazione dello schema garantita sui nomi e gli input degli strumenti.

Perché usare 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 parsing 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 decodifica vincolata:

• Sempre valido: Niente più errori JSON.parse()
• Type safe: Tipi di campo garantiti e campi obbligatori
• Affidabile: Nessun nuovo tentativo necessario per violazioni dello schema
• Due modalità: JSON per attività come l'estrazione di dati, e strumenti rigorosi per situazioni come strumenti complessi e flussi di lavoro agentici

Avvio rapido

Quando usare output JSON vs uso rigoroso degli strumenti

Scegli la modalità giusta per il tuo caso d'uso:

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

La costruzione di sistemi agentici affidabili richiede conformità dello schema garantita. I parametri dello strumento non validi interrompono le tue funzioni e i tuoi flussi di lavoro. Claude potrebbe restituire tipi incompatibili ("2" invece di 2) o campi mancanti, 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 di 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 modalità rigorosa, Claude potrebbe fornire passengers: "two" o passengers: "2". Con strict: true, sei garantito passengers: 2.

Come funzionano gli output strutturati

Lavorare con output JSON negli SDK

Gli SDK Python e TypeScript forniscono helper che rendono più facile lavorare con output JSON, inclusa la trasformazione dello schema, la validazione 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.

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

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 vuoi modificare uno schema generato da Pydantic. A differenza di client.beta.messages.parse(), che trasforma automaticamente gli schemi forniti, questo ti dà 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 funzioni non supportate:

1. Rimuovi 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 validazione.

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

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_format invaliderà qualsiasi cache del prompt per quel thread di conversazione

Limitazioni dello schema JSON

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 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 (il rifiuto ha la precedenza)

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 validazione dello schema

Se il tuo schema utilizza funzioni 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 funzioni

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: Usa output JSON (output_format) e 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 è in conflitto con i vincoli dello schema JSON rigoroso. Restituisce errore 400 se le citazioni sono abilitate con output_format.
• Prefilling dei messaggi: Incompatibile con output JSON