Output strutturato (JSON Schema)
L'output strutturato fa sì che le risposte di un agente siano un oggetto JSON conforme a uno schema definito, invece di un testo libero in linguaggio naturale.
Prerequisiti
- Un agente esistente e il permesso di modificarlo.
- Conoscenza di base della sintassi JSON Schema.
Quando usare l'output strutturato
L'output strutturato è utile quando la risposta dell'agente deve essere letta da un altro sistema, ad esempio per estrarre dati da un documento o per produrre un oggetto con campi obbligatori destinato a un report o a un'integrazione. Non è indicato per le conversazioni discorsive rivolte a un utente finale.
Definire lo schema
- Nella pagina dell'agente, aprire la sezione Avanzate.
- Attivare l'interruttore Abilita output strutturato.
- Scrivere o incollare lo JSON Schema nell'editor che compare sotto l'interruttore. Sotto l'editor è riportato un esempio di schema minimo.
- Controllare che sotto l'editor non compaia il messaggio JSON Schema non valido, seguito dalla descrizione dell'errore.
Lo schema viene verificato mentre si scrive e deve essere un oggetto JSON. Finché non è valido, la configurazione non viene salvata. Quando l'output strutturato è attivo, l'intestazione della sezione Avanzate lo riporta nel riepilogo.
Il modo in cui la risposta aderisce allo schema dipende dal provider del modello scelto: alcuni provider lo garantiscono in modo nativo, altri lo ottengono tramite istruzioni aggiuntive al modello, con un'aderenza meno rigorosa.
Output strutturato e connettori
Quando all'agente sono collegati connettori attivi, i cui strumenti vengono messi a disposizione del modello, lo schema non viene applicato e l'agente risponde in forma libera. La console lo ricorda nella descrizione dell'interruttore Abilita output strutturato. Per ottenere risposte conformi allo schema, l'agente non deve avere connettori attivi nella sezione Strumenti e connettori.
Esempio pratico
Uno schema minimo per ottenere un riepilogo strutturato di una segnalazione può essere il seguente:
{
"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 è un oggetto JSON con 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 | All'agente sono collegati connettori attivi | Rimuovere i connettori dalla sezione Strumenti e connettori se serve l'output strutturato |
| Compare JSON Schema non valido e la configurazione non si salva | Sintassi JSON errata, oppure lo schema non è un oggetto | Correggere l'errore indicato sotto l'editor |
| Il JSON restituito non rispetta sempre lo schema | Il provider del modello non garantisce l'aderenza in modo nativo | Provare un modello di un altro provider tra quelli disponibili |