Claude Platform Docs
MessaggiCapacità del modello

Output strutturati

Ottieni risultati JSON convalidati dai flussi di lavoro degli agenti

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.
  • 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 interrompono 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 “constrained decoding” (decodifica vincolata):

  • Sempre validi: nessun errore di parsing JSON
  • Type safe: tipi dei campi e campi obbligatori garantiti
  • Affidabili: nessun nuovo tentativo necessario per violazioni dello schema

Come funziona

  1. Definisci il tuo schema

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

  2. Invialo in output_config.format

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

  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 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)

Passa un modello Pydantic a client.messages.parse(), il metodo consigliato, come output_format. L’SDK trasforma lo schema del modello, lo invia come output_config.format, convalida la risposta e restituisce il modello analizzato in parsed_output.

L’esempio precedente produce:

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

Se conosci le chiavi di un campo, usa un modello Pydantic annidato, non un dict. L’SDK invia un campo dict come oggetto con properties vuoto, quindi Claude può restituire solo {} per quel campo. Se non conosci le chiavi in anticipo, consulta Oggetti con chiavi arbitrarie.

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 ogni 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 supportato
  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 un JSON schema grezzo

Per usare un JSON schema 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)

L’esempio precedente produce:

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

Per spostare i vincoli non supportati dall’API nelle descrizioni dei campi, passa lo schema attraverso transform_schema() del pacchetto anthropic prima di inviarlo, e modifica il risultato se necessario. transform_schema() accetta anche un modello Pydantic. A differenza di client.messages.parse(), restituisce lo schema trasformato anziché inviarlo.

Casi d’uso comuni

Uso rigoroso degli strumenti

Per imporre la conformità a JSON Schema sugli input degli strumenti con il campionamento vincolato dalla grammatica, consulta 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 della risposta di Claude (cosa dice Claude).
  • L’uso rigoroso degli strumenti convalida i parametri degli strumenti (come Claude chiama le tue funzioni).

Quando vengono combinati, Claude può chiamare strumenti con parametri garantiti come validi E restituire risposte JSON strutturate. Questo è utile per i flussi di lavoro agentici in cui servono sia chiamate agli strumenti affidabili sia output finali strutturati.

client = anthropic.Anthropic()

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 della grammatica e cache

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

  • 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 del JSON schema oppure, quando usi sia gli output strutturati sia l’uso degli strumenti, l’insieme degli strumenti nella tua richiesta. 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. Ciò significa che:

  • Il conteggio dei token di input è leggermente più alto.
  • Il prompt iniettato ti costa token come qualsiasi altro prompt di sistema.
  • Modificare il parametro output_config.format invalida 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.

Oggetti con chiavi arbitrarie

Elenca ogni chiave di un oggetto, in properties oppure come campo della classe o dello schema che passi all’SDK. Poiché additionalProperties deve essere false, Claude può restituire solo le chiavi che elenchi.

L’API accetta un oggetto con properties vuoto o mancante, ma Claude può restituire solo {} per esso. Un tipo map, dizionario o record non elenca alcuna chiave, quindi gli SDK Python e TypeScript lo inviano come oggetto con properties vuoto. Gli SDK Java e Ruby sollevano invece un errore.

Se non conosci le chiavi in anticipo, usa invece un array. Assegna a ogni elemento una key e un value, come in questo schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}

Ordinamento delle proprietà

Quando usi gli output strutturati, le proprietà negli oggetti mantengono l’ordine definito nel tuo schema, con un’importante avvertenza: le proprietà obbligatorie compaiono per prime, seguite dalle proprietà facoltative.

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 ordina le proprietà in questo modo:

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

Ciò 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 potrebbe 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 perché ha 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/minuscole dei valori enum

Gli output strutturati non garantiscono l’uso delle maiuscole nei valori stringa di enum e const: Claude potrebbe 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 potrebbe contenere "Conversation Topic 3" (“T” maiuscola) anche se quel valore esatto non è presente 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 JSON schema 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:

LimiteValoreDescrizione
Strumenti rigorosi per richiesta20Numero massimo di strumenti con strict: true. Gli strumenti non rigorosi non vengono conteggiati ai fini di questo limite.
Parametri facoltativi24Totale dei parametri facoltativi in tutti gli schemi degli strumenti rigorosi e negli schemi di output JSON. Ogni parametro non elencato in required viene conteggiato ai fini di questo limite.
Parametri con tipi unione16Totale dei parametri che usano anyOf o array di tipi (ad esempio, "type": ["string", "null"]) in tutti gli schemi rigorosi. Sono particolarmente onerosi perché generano un costo di compilazione esponenziale.

Limiti interni aggiuntivi

Oltre ai limiti espliciti della 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 facoltativi, 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 indicano che la complessità combinata dei tuoi schemi supera ciò che può essere compilato in modo efficiente, anche se ogni singolo limite della tabella precedente è rispettato. 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:

  1. Contrassegna come rigorosi solo gli strumenti critici. Se hai molti strumenti, riserva l’uso rigoroso degli strumenti a quelli 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 facoltativi. Rendi i parametri required dove possibile. Ogni parametro facoltativo raddoppia approssimativamente una porzione dello spazio degli stati della grammatica. Se un parametro ha sempre un valore predefinito ragionevole, valuta di renderlo obbligatorio e di far fornire esplicitamente quel valore predefinito a Claude.

  3. Semplifica le strutture annidate. Oggetti profondamente annidati con campi facoltativi aumentano la complessità. Appiattisci le strutture dove possibile.

  4. Suddividi in più richieste. Se hai molti strumenti rigorosi, valuta di suddividerli in richieste separate o in subagenti.

Per problemi persistenti con schemi validi, contatta il supporto fornendo 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. Per usarlo comunque, aggiungi l’header beta structured-outputs-2025-11-13. Senza di esso, l’API restituisce un errore 400.

Nell’SDK Python (v1.0 e successive), un dizionario di schema passato come output_format={...} solleva un TypeError. Usa invece output_config. Un modello Pydantic passato come output_format=Model a parse() o stream() funziona senza modifiche e senza header beta, perché l’SDK lo invia come output_config. Consulta Usare un JSON schema grezzo per la forma aggiornata dell’API.

Compatibilità delle funzionalità

Funziona con:

  • Elaborazione batch: elabora output strutturati su larga scala con uno sconto del 50 percento
  • 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 di intercalare blocchi di citazione con il testo, il che è in conflitto con i vincoli rigorosi del JSON schema. L’API restituisce un errore 400 se le citazioni sono abilitate con output_config.format. Per estrarre dati strutturati con una citazione per ogni valore, consulta Ottenere dati strutturati con citazioni.
  • Precompilazione dei messaggi: la precompilazione è incompatibile con gli output JSON.

Disponibilità

Output strutturati
API
  • Messages API
  • Managed Agents Non supportato
Modelli
  • Tutti i modelli

Endpoint applicabili

  • /v1/messages
Conservazione zero dei datiIdoneo (con riserva)

Esclude Modelli coperti

I tuoi prompt e gli output di Claude non vengono archiviati. Solo lo JSON schema viene memorizzato nella cache, per un massimo di 24 ore dall’ultimo utilizzo. Ciò copre anche l’uso rigoroso degli strumenti (strict: true sugli strumenti), che usa la stessa pipeline grammaticale. Scopri di più

HIPAAIdoneo

Le PHI non devono essere incluse nelle definizioni di JSON schema; consulta le linee guida sulla gestione delle PHI. Scopri di più

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

Gli output strutturati sono idonei HIPAA, ma le PHI non devono essere incluse nelle definizioni dei JSON schema. L’API compila i JSON schema in grammatiche che vengono memorizzate nella cache separatamente dal contenuto dei messaggi, e questi schemi memorizzati nella 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 devono comparire solo nel contenuto dei messaggi (prompt e risposte), dove sono protette dalle garanzie HIPAA.

Passaggi successivi

Fai in modo che Claude citi le sue fonti quando risponde a domande sui documenti forniti.

Imponi la conformità a JSON Schema sugli input degli strumenti di Claude con il campionamento vincolato dalla grammatica.

Collega Claude a strumenti e API esterni. Scopri dove vengono eseguiti gli strumenti e come funziona il ciclo agentico.

Scopri la struttura dei prezzi di Anthropic per modelli e funzionalità.

Questa pagina ti è stata utile?