Output strutturati

Gli output strutturati vincolano le risposte di Claude a seguire uno schema specifico, garantendo output validi e analizzabili per l'elaborazione a valle. Gli output strutturati offrono due funzionalità complementari:

• Output JSON (output_config.format): Ottieni la risposta di Claude in un formato JSON specifico
• Uso degli strumenti rigoroso (strict: true): Garantisci la validazione dello schema sui nomi e gli input degli strumenti

Puoi utilizzare queste funzionalità in modo indipendente o 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 riscontrare:

• 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 JSON.parse()
• Type safe: Tipi di campo e campi obbligatori garantiti
• Affidabili: Nessun nuovo tentativo necessario per violazioni dello schema



Output JSON

Gli output JSON controllano il formato di risposta di Claude, garantendo che Claude restituisca JSON valido corrispondente al tuo schema. Usa gli output JSON quando devi:

• Controllare il formato di risposta di Claude
• Estrarre dati da immagini o testo
• Generare report strutturati
• Formattare risposte API



Avvio rapido

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    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_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,
            },
        }
    },
)
print(response.content[0].text)

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 forniscono helper che semplificano il lavoro con gli output JSON, inclusa la trasformazione dello schema, la validazione automatica e l'integrazione con le librerie di schema più diffuse.



Utilizzo di definizioni di schema native

Invece di scrivere schemi JSON grezzi, puoi utilizzare strumenti di definizione dello schema familiari nel tuo linguaggio:

• Python: Modelli Pydantic con client.messages.parse()
• TypeScript: Schemi Zod con zodOutputFormat() o literal JSON Schema tipizzati con jsonSchemaOutputFormat()
• Java: Classi Java semplici con derivazione automatica dello schema tramite outputConfig(Class<T>)
• Ruby: Classi Anthropic::BaseModel con output_config: {format: Model}
• PHP: Classi che implementano StructuredOutputModel con outputConfig: ['format' => MyClass::class]
• C#: Classi C# semplici con l'overload generico Create<T>(), che deriva automaticamente lo schema
• Go: Struct Go riflesse automaticamente in schemi JSON sull'API beta, o schemi JSON grezzi tramite output_config
• CLI: Schemi JSON grezzi passati tramite output_config

from pydantic import BaseModel
from anthropic import Anthropic


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


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=1024,
    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 per SDK

Ogni SDK fornisce helper che semplificano il lavoro con gli output strutturati. Consulta le pagine dei singoli SDK per i dettagli completi.



Come funziona la trasformazione SDK

Gli SDK Python, TypeScript, Ruby e PHP trasformano automaticamente gli schemi con funzionalità non supportate. Gli SDK C# e Go applicano le stesse trasformazioni quando lo schema è derivato da un tipo nativo (Create<T>() in C#; riflessione di struct o BetaJSONSchemaOutputFormat() sull'API beta di Go). I passaggi di trasformazione:

1. Rimuovere i vincoli non supportati (ad esempio, minimum, maximum, minLength, maxLength)
2. Aggiornare le descrizioni con informazioni sui vincoli (ad esempio, "Must be at least 100"), quando il vincolo non è direttamente supportato con gli output strutturati
3. Aggiungere additionalProperties: false a tutti gli oggetti
4. Filtrare i formati stringa solo all'elenco supportato
5. Validare le risposte rispetto al tuo schema originale (con tutti i vincoli)

Questo significa che Claude riceve uno schema semplificato, ma il tuo codice applica comunque tutti i vincoli tramite validazione.

Esempio: Un campo Pydantic con minimum: 100 diventa un intero semplice nello schema inviato, ma l'SDK aggiorna la descrizione a "Must be at least 100" e valida la risposta rispetto al vincolo originale.



Casi d'uso comuni



Uso degli strumenti rigoroso

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



Utilizzo di entrambe le funzionalità insieme

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

• Gli output JSON controllano il formato di risposta di Claude (cosa dice Claude)
• L'uso degli strumenti rigoroso 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 flussi di lavoro agentici in cui hai bisogno sia di chiamate agli strumenti affidabili che di output finali strutturati.

response = client.messages.create(
    model="claude-opus-4-8",
    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 caching della grammatica

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

• Latenza della prima richiesta: La prima volta che usi uno schema specifico, c'è 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 usi sia output strutturati che uso degli strumenti)
  • Modificare solo i campi name o description non invalida la cache



Modifica del prompt e costi in token

Quando usi gli output strutturati, Claude riceve automaticamente un prompt di sistema aggiuntivo che spiega il formato di output previsto. Questo 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 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 che l'uso degli strumenti rigoroso condividono queste limitazioni.



Ordinamento delle proprietà

Quando usi gli output strutturati, le proprietà negli oggetti mantengono l'ordinamento definito dal 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": "[email protected]",
  "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, 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 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

Limite di token raggiunto (stop_reason: "max_tokens")

Se la risposta viene troncata a causa del raggiungimento del 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



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 la compilazione. Per proteggere 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, ci sono 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 union, 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 è soddisfatto. 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 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 per gli 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 far sì che Claude fornisca esplicitamente quel valore predefinito.

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

4. Dividi in più richieste. Se hai molti strumenti strict, considera di dividerli in richieste separate o sub-agenti.

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



Conservazione dei dati

I prompt e le risposte vengono elaborati con ZDR quando si utilizzano gli output strutturati. Tuttavia, lo schema JSON stesso viene temporaneamente memorizzato nella cache per un massimo di 24 ore dall'ultimo utilizzo a scopo 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 dello schema JSON. L'API compila gli schemi JSON 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 apparire solo nel contenuto dei messaggi (prompt e risposte), dove sono protette dalle salvaguardie HIPAA.

Per l'idoneità ZDR e HIPAA su 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 risposte normali
• Utilizzo combinato: Usa output JSON (output_config.format) e uso degli strumenti rigoroso (strict: true) insieme nella stessa richiesta

Incompatibile con:

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



Passaggi successivi