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
• Strict tool use (uso rigoroso degli strumenti) (strict: true): garantisci la validazione dello schema sui nomi e sugli input degli strumenti

Puoi usare 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 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

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 hai bisogno di:

• 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-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,
            },
        }
    },
)
print(next(block.text for block in response.content if block.type == "text"))

Formato della risposta: JSON valido corrispondente al tuo schema nel blocco di contenuto testuale della risposta

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

Come funziona

1. 1

   Definisci il tuo schema JSON

   Crea uno schema JSON che descriva la struttura che vuoi che Claude segua. Lo schema usa il formato JSON Schema standard con alcune limitazioni (vedi Limitazioni di JSON Schema).

2. 2

   Aggiungi il parametro output_config.format

   Includi il parametro output_config.format nella tua richiesta API con type: "json_schema" e la definizione del tuo schema.

3. 3

   Analizza la risposta

   La risposta di Claude è JSON valido corrispondente al tuo schema, restituito nel blocco di contenuto testuale della risposta.

Lavorare con gli output JSON negli SDK

Gli SDK forniscono helper che semplificano il lavoro con gli output JSON, tra cui la trasformazione degli schemi, la validazione automatica e l'integrazione con le librerie di schemi più diffuse.

Usare definizioni di schema native

Invece di scrivere schemi JSON grezzi, puoi usare gli strumenti di definizione degli schemi familiari nel tuo linguaggio:

• Python: modelli Pydantic con client.messages.parse()
• TypeScript: schemi Zod con zodOutputFormat() o letterali 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 lo schema automaticamente
• Go: struct Go riflesse automaticamente in schemi JSON sull'API beta, oppure 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-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)

Metodi specifici degli SDK

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

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Accedi direttamente all'output analizzato
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# Prima converti il modello Pydantic in JSON schema, poi trasformalo
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# Modifica lo schema se necessario
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)

Come funziona la trasformazione degli 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 della trasformazione:

1. Rimuovere i vincoli non supportati (ad esempio, minimum, maximum, minLength, maxLength)
2. Aggiornare le descrizioni con le informazioni sui vincoli (ad esempio, "Must be at least 100"), quando il vincolo non è supportato direttamente dagli output strutturati
3. Aggiungere additionalProperties: false a tutti gli oggetti
4. Filtrare i formati di stringa lasciando solo quelli dell'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 la validazione.

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

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

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.

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