Output strutturato (JSON Schema)
L'output strutturato forza le risposte di un agente a rispettare un formato JSON conforme a uno schema definito, invece di lasciare libera la generazione in linguaggio naturale.
Prerequisiti
- Un agente esistente su cui attivare la funzionalità.
- Conoscenza di base della sintassi JSON Schema.
Quando usare l'output strutturato
L'output strutturato è utile quando la risposta dell'agente deve essere consumata da un altro sistema (integrazione machine-to-machine) o da un componente dell'interfaccia che si aspetta campi precisi, ad esempio l'estrazione di dati da un documento o la generazione di un oggetto con campi obbligatori per un report. Non è indicato per conversazioni discorsive rivolte a un utente finale.
Definire lo schema
- Attivare il toggle Output strutturato nella configurazione dell'agente.
- Scrivere o incollare nell'editor lo JSON Schema che descrive la struttura attesa della risposta.
- La piattaforma valida lo schema in tempo reale, segnalando eventuali errori di sintassi.
A seconda del provider selezionato per l'agente, l'aderenza allo schema è garantita in modo diverso: nativamente tramite structured output sui modelli OpenAI e Google, tramite istruzioni aggiuntive nel prompt sui modelli Anthropic e Mistral.
Incompatibilità con gli strumenti
Un agente non può avere contemporaneamente l'output strutturato attivo e strumenti MCP configurati. Se l'agente ha entrambi impostati, prevalgono i tool: lo schema di output viene ignorato finché i server MCP restano collegati.
Esempio pratico
Uno schema minimo per estrarre un riepilogo strutturato di un ticket potrebbe essere:
{
"type": "object",
"properties": {
"categoria": { "type": "string" },
"urgenza": { "type": "string", "enum": ["bassa", "media", "alta"] },
"riassunto": { "type": "string" }
},
"required": ["categoria", "urgenza", "riassunto"]
}
Con questo schema attivo, ogni risposta dell'agente sarà un oggetto JSON con esattamente questi tre campi, senza testo aggiuntivo prima o dopo.
Problemi comuni
| Problema | Causa probabile | Soluzione |
|---|---|---|
| L'agente ignora lo schema e risponde in linguaggio naturale | Sono collegati anche server MCP all'agente | Scollegare i server MCP se si vuole garantire l'output strutturato |
| Lo schema viene rifiutato al salvataggio | Sintassi JSON Schema non valida | Correggere gli errori segnalati dalla validazione in tempo reale |
| Il JSON restituito non rispetta sempre lo schema sui modelli Anthropic o Mistral | Questi provider non hanno structured output nativo | Preferire un modello OpenAI o Google per un'aderenza garantita allo schema |