Passa al contenuto principale

Output strutturato

Intermedio
What you'll learn
  • Spiegare perché l'output vincolato a uno schema batte il prompt che chiede JSON sperando nel meglio
  • Fornire un JSON Schema e fare il parsing della risposta in un oggetto tipizzato (Pydantic / Zod)
  • Distinguere l'output strutturato dall'uso degli strumenti per intento, non per meccanismo
  • Applicare i quattro consigli per schemi rigorosi e affidabili
  • Scegliere lo strumento giusto con una regola pratica basata su una sola domanda

Quando l'output di Claude alimenta altro software, ti serve una struttura affidabile — JSON valido che corrisponde a una forma nota, ogni volta. Non affidarti al "rispondi in JSON" sperando che vada bene; usa il supporto all'output strutturato della piattaforma.

Questa lezione ti accompagna da perché il prompt-e-prega fallisce a come imporre uno schema e farne il parsing in un oggetto tipizzato — e a come distinguere l'output strutturato dall'uso degli strumenti quando sembrano identici. Affrontala dall'inizio alla fine, poi mettiti alla prova con il quiz verso la fine.

Il modo affidabile​

Fornisci un JSON Schema per l'output e lascia che l'API/l'SDK lo imponga, poi effettua il parsing in un oggetto tipizzato (ad esempio Pydantic in Python, Zod in TypeScript). Gli helper di parsing dell'SDK ti consegnano un risultato tipizzato invece di una stringa che devi sottoporre a JSON.parse e validare da solo.

Guided walkthrough1 of 3
  1. Modella l'output che ti serve come JSON Schema — in Python tramite un Pydantic BaseModel, in TypeScript tramite uno schema Zod.
# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

Vuoi una richiesta concreta da adattare? Ecco la forma di ciò che passi al modello — sostituisci il modello con il tuo schema.

Chiedi output conforme allo schema

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

Perché non chiedere semplicemente il JSON nel prompt?​

Puoi chiedere il JSON nel prompt, e per i casi semplici funziona — ma può deviare: prosa di troppo, una virgola finale, un campo mancante. L'output imposto da schema elimina quella classe di bug, il che conta nel momento in cui un sistema a valle ne dipende.

Watch out
  • Il JSON chiesto via prompt funziona nelle demo e si rompe in produzione: il guasto compare solo quando un sistema a valle ne fa il parsing.
  • Tre derive classiche da tenere d'occhio: prosa di troppo intorno al JSON, una virgola finale, un campo obbligatorio mancante.

Output strutturato vs. uso degli strumenti​

Entrambe le funzionalità forniscono al modello uno JSON Schema, quindi si assomigliano — e si finisce per scegliere quella sbagliata. La differenza sta nell'intento, non nel meccanismo:

Output strutturatoUso degli strumenti
Cosa vuoiLa risposta finale, in una forma fissaChe il modello invochi una capacità (chiami una funzione, recuperi dati, esegua un'azione)
Chi la consumaIl tuo codice, direttamenteIl tuo codice esegue lo strumento, poi restituisce il risultato al modello
Forma del turnoUna risposta, finitaUn ciclo: il modello chiede, tu esegui, il modello continua
Uso tipicoEstrazione, classificazione, parsingAgenti, ricerche in tempo reale, effetti collaterali

Una rapida regola pratica:

Se il JSON è il prodotto finale, usa l'output strutturato. Se il JSON è il modello che chiede al tuo codice di fare qualcosa, allora è uso degli strumenti. Gli agenti spesso usano entrambi: gli strumenti per agire, l'output strutturato per restituire un risultato finale pulito.

Suggerimenti​

Pro tip
  • Mantieni gli schemi rigorosi — usa gli enum per le scelte fisse; marca i campi obbligatori.
  • Descrivi i campi — le descrizioni dei campi guidano il modello come mini-prompt.
  • Valida comunque al confine — un parsing difensivo è un'assicurazione economica.
  • Per i task di estrazione, output strutturato + uno schema chiaro batte il formato libero ogni volta.
Key takeaways
  • Passa all'API/all'SDK un JSON Schema e fai il parsing in un oggetto tipizzato — non il prompt-e-prega.
  • Chiedere il JSON nel prompt può deviare (prosa di troppo, virgola finale, campo mancante); l'imposizione dello schema elimina quella classe di bug.
  • Output strutturato vs. uso degli strumenti differiscono per intento: il JSON È la risposta vs. il JSON richiede un'azione.
  • Schemi rigorosi, campi descritti e validazione al confine rendono affidabili estrazione e classificazione.

Fissa i termini​

Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 5

Mettiti alla prova

0/4
  1. Qual è il modo affidabile per ottenere JSON strutturato da Claude?
  2. Perché chiedere il JSON nel prompt è rischioso una volta che un sistema a valle ne dipende?
  3. Cosa distingue davvero l'output strutturato dall'uso degli strumenti?
  4. Quale di questi è un consiglio valido per progettare gli schemi?

Avanti​