Output strutturati

Gli "structured outputs" (output strutturati) vincolano le risposte di Claude a seguire uno schema specifico, garantendo un output valido e analizzabile per l'elaborazione a valle. Gli output strutturati forniscono due funzionalità complementari:

• Output JSON (output_config.format): ottieni la risposta di Claude in un formato JSON specifico, ad esempio per estrarre dati da immagini o testo, generare report strutturati o formattare risposte API. Questa pagina tratta gli output JSON.
• "Strict tool use" (uso rigoroso degli strumenti) (strict: true): garantisci la convalida dello schema sui nomi e sugli input degli strumenti. Consulta Uso rigoroso degli strumenti.

Puoi usare queste funzionalità in modo indipendente oppure 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 compromettono le tue applicazioni. Anche con un prompting accurato, potresti incontrare:

• Errori di parsing dovuti a 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 di JSON.parse()
• Type safe: tipi di campo e campi obbligatori garantiti
• Affidabili: nessun nuovo tentativo necessario per violazioni dello schema

Come funziona

1. 1

   Definisci il tuo schema

   Descrivi la struttura che desideri come schema JSON o come tipo nel tuo linguaggio. Lo schema segue JSON Schema, con alcune limitazioni.

2. 2

   Invialo in output_config.format

   La richiesta trasporta lo schema in output_config.format con type: "json_schema". Gli helper dell'SDK lo impostano per te.

3. 3

   Leggi la risposta

   Claude restituisce JSON valido che corrisponde al tuo schema nel blocco di contenuto testuale della risposta. Gli helper dell'SDK lo analizzano e lo convertono nel tuo tipo.

Utilizzo

from pydantic import BaseModel
# ...


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


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

Come funziona la trasformazione dell'SDK

La maggior parte degli helper dell'SDK trasforma gli schemi che usano funzionalità non supportate. I passaggi della trasformazione:

1. Rimuove i vincoli non supportati (ad esempio, minimum, maximum, minLength, maxLength)
2. Aggiorna le descrizioni aggiungendo ciascun vincolo non supportato alla descrizione del campo (ad esempio, {minimum: 100})
3. Aggiunge additionalProperties: false a tutti gli oggetti
4. Filtra i formati delle stringhe limitandoli all'elenco di quelli supportati
5. Convalida le risposte rispetto al tuo schema originale e a tutti i suoi vincoli, se l'helper convalida le risposte

Claude riceve uno schema semplificato, ma un helper che convalida le risposte applica comunque ogni vincolo nel tuo codice.

Esempio: un campo con minimum: 100 diventa un semplice intero nello schema inviato, e l'SDK aggiunge {minimum: 100} alla descrizione del campo. Un helper che convalida le risposte verifica comunque la risposta rispetto a minimum: 100.

Usare uno schema JSON grezzo

Per usare uno schema JSON proveniente da un file, da una specifica OpenAPI o da codice che lo costruisce in fase di esecuzione, passalo in output_config.format.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

Casi d'uso comuni

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

Uso rigoroso degli strumenti

Per imporre la conformità a JSON Schema sugli input degli strumenti con campionamento vincolato da grammatica, vedi Uso rigoroso degli strumenti.

Usare entrambe le funzionalità insieme

Gli output JSON e l'uso rigoroso degli strumenti risolvono problemi diversi e funzionano insieme:

• Gli output JSON controllano il formato di risposta di Claude (cosa dice Claude)
• L'uso rigoroso degli strumenti valida i parametri degli strumenti (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 agli strumenti affidabili sia di output finali strutturati.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # Output JSON: formato di risposta strutturato
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # Uso degli strumenti rigoroso: parametri degli strumenti garantiti
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

Considerazioni importanti

Compilazione e cache delle grammatiche

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

• Latenza della prima richiesta: la prima volta che usi uno schema specifico, c'è una "latency" (latenza) aggiuntiva mentre la grammatica viene compilata
• Cache automatica: 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 usi sia gli output strutturati sia l'uso degli strumenti)
  • Modificare solo i campi name o description non invalida la cache

Modifica del prompt e costi dei token

Quando usi gli output strutturati, Claude riceve automaticamente un "system prompt" (prompt di sistema) aggiuntivo che spiega il formato di output previsto. Questo significa che:

• Il conteggio dei tuoi token di input è leggermente più alto
• Il prompt iniettato ti costa token come qualsiasi altro prompt di sistema
• Modificare il parametro output_config.format invaliderà qualsiasi cache dei prompt per quel thread di conversazione

Limitazioni di JSON Schema

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

Ordinamento delle proprietà

Quando usi gli output strutturati, le proprietà negli oggetti mantengono l'ordinamento definito nel tuo schema, con un'importante avvertenza: le proprietà obbligatorie appaiono per prime, 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 segue:

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

Questo significa che l'output potrebbe apparire così:

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

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

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 usa gli output strutturati. Se Claude rifiuta una richiesta per motivi di sicurezza:

• La risposta ha 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

Una proprietà che richiede il "thinking" (ragionamento) del modello o un ragionamento passo dopo passo può portare a un rifiuto reasoning_extraction. Chiedi invece una breve spiegazione. Consulta Mantieni il ragionamento nei blocchi di ragionamento.

Limite di token raggiunto (stop_reason: "max_tokens")

Se la risposta viene troncata per aver raggiunto il limite max_tokens:

• La risposta ha 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

Maiuscole e minuscole nei valori enum

Gli output strutturati non garantiscono l'uso delle maiuscole nei valori enum e const di tipo stringa: Claude può restituire un valore che differisce dal tuo schema solo per le maiuscole, tipicamente nella prima lettera di una parola che segue uno spazio. Ad esempio, dato questo schema:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

L'output può contenere "Conversation Topic 3" ("T" maiuscola) anche se quel valore esatto non è nell'enum. La risposta si completa normalmente, senza errori e senza uno stop_reason speciale. Questo vale sia per gli output JSON sia per l'uso rigoroso degli strumenti. Confronta i valori enum senza distinzione tra maiuscole e minuscole ed evita valori enum che differiscono solo per le maiuscole.

Limiti di complessità dello schema

Gli output strutturati funzionano compilando i tuoi schemi JSON in una grammatica che vincola l'output di Claude. 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 nella tabella precedente, 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 nella tabella precedente è rispettato. Come ultima misura di salvaguardia, 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 possono raggiungere questo timeout.

Suggerimenti per ridurre la complessità dello schema

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

1. Contrassegna come strict solo gli strumenti critici. 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 a Claude quel valore predefinito.

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

4. Suddividi in più richieste. Se hai molti strumenti strict, considera di suddividerli in richieste separate o sotto-agenti.

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

Migrazione dalla beta

Il parametro output_format è stato spostato in output_config.format e gli header beta non sono più necessari. Il parametro output_format è deprecato e verrà rimosso in futuro. Per usarlo comunque, aggiungi l'header beta structured-outputs-2025-11-13. Senza di esso, l'API restituisce un errore 400.

L'SDK Python (v1.0 e successive) non accetta output_format={...} su client.beta.messages.create() o count_tokens() e solleva un TypeError. Usa invece output_config. Consulta Usare uno schema JSON grezzo per la forma aggiornata dell'API.

Conservazione dei dati

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

Gli output strutturati sono idonei per HIPAA, ma le PHI non devono essere incluse nelle definizioni degli schemi JSON. L'API compila gli schemi JSON in grammatiche che vengono memorizzate nella cache separatamente dal contenuto dei messaggi, e questi schemi in cache non ricevono le stesse protezioni PHI dei prompt e delle risposte. Non includere PHI nei nomi delle proprietà dello schema, nei valori enum, nei valori const o nelle espressioni regolari pattern. Le PHI dovrebbero apparire solo nel contenuto dei messaggi (prompt e risposte), dove sono protette dalle garanzie HIPAA.

Per l'idoneità ZDR e HIPAA di tutte le funzionalità, vedi API e conservazione dei dati.

Compatibilità delle funzionalità

Funziona con:

• Elaborazione batch: elabora output strutturati su larga scala con uno sconto del 50%
• Conteggio dei token: conta i token senza compilazione
• Streaming: trasmetti in streaming gli output strutturati come le normali risposte
• Uso combinato: usa gli output JSON (output_config.format) e l'uso rigoroso degli strumenti (strict: true) insieme nella stessa richiesta

Incompatibile con:

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

Passaggi successivi

Compatibility