Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Definire le funzioni con JSON Schema

Lezione 3 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Il contratto tra il tuo codice e il modello
  2. Anatomia di una specifica di strumento
  3. Tipi JSON Schema supportati
  4. Esempio completo: due funzioni complementari
  5. Parametri obbligatori vs opzionali
  6. Migliori pratiche per le descrizioni
  7. Punti chiave

Il contratto tra il tuo codice e il modello

Affinché il modello Mistral possa chiamare le tue funzioni, deve sapere cosa esiste e come utilizzarlo. Questo è il ruolo dello JSON Schema: un formato standardizzato che descrive ogni funzione—il suo nome, cosa fa, quali parametri si aspetta e quali sono obbligatori.

Tieni a mente una cosa fondamentale durante questa lezione: il modello non vede mai il tuo codice Python. Vede solo questa specifica. Se la tua funzione gestisce correttamente gli ID in minuscolo ma lo schema non lo specifica, il modello ignorerà quella capacità. Più il tuo schema è preciso e ben documentato, più accurati saranno gli argomenti generati.

Anatomia di una specifica di strumento

Ogni strumento inviato alle API di Mistral segue la stessa struttura:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
CampoRuolo
typeSempre "function" (altri tipi potrebbero esistere in futuro)
function.nameIl nome esatto della tua funzione Python: è ciò che il modello restituisce in tool_calls
function.descriptionUna frase chiara che aiuta il modello a scegliere la funzione corretta
function.parametersUn oggetto JSON Schema che descrive i parametri attesi
requiredL’elenco dei parametri obbligatori

Tipi JSON Schema supportati

Il vocabolario dei tipi disponibili per descrivere i parametri è intenzionalmente limitato e ogni tipo guida il modello in modo diverso. Un enum, in particolare, fa più che documentare: chiude la porta ai valori inventati.

# String — testo libero o vincolato
{"type": "string", "description": "Transaction ID"}

# String with enum — valori limitati
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — numero intero
{"type": "integer", "description": "Number of results to return"}

# Number — numero decimale
{"type": "number", "description": "Amount in euros"}

# Boolean — vero/falso
{"type": "boolean", "description": "Include canceled transactions"}

# Array — lista di valori
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — oggetto annidato
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Distingui chiaramente tra integer e number: un importo in euro come 125,50 richiede un number, mentre un conteggio di risultati da restituire è un integer. Dichiarare un importo come integer costringerà il modello ad arrotondarlo.

Esempio completo: due funzioni complementari

Ecco un esempio realistico con due funzioni relative ai pagamenti, ispirato alla documentazione ufficiale di Mistral:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Entrambe le funzioni si aspettano esattamente lo stesso parametro, transaction_id, eppure il modello deve scegliere tra di esse. Questa scelta si basa interamente sulla descrizione della funzione. “Questo pagamento è andato a buon fine?” corrisponde a retrieve_payment_status; “Quando è stato effettuato?” corrisponde a retrieve_payment_date. Se avessi scritto due descrizioni vaghe e intercambiabili, il modello sbaglierebbe metà delle volte: daresti la colpa al modello, mentre la colpa risiederebbe nello schema.

Parametri obbligatori vs opzionali

La distinzione tra parametri obbligatori e opzionali determina ciò che il modello ha il permesso di omettere.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Qui, solo status è obbligatorio; gli altri parametri vengono inclusi solo se l’utente li menziona. Confronta due formulazioni. Per “Mostrami i pagamenti falliti”, il modello genera semplicemente {"status": "failed"}. Per “Mostrami i pagamenti falliti da marzo 2026”, aggiunge autonomamente date_from e date_to. Rendere quelle date obbligatorie avrebbe rotto la prima query o, peggio, spinto il modello a inventare un intervallo di date.

Migliori pratiche per le descrizioni

La qualità della descrizione impatta direttamente sull’accuratezza del modello. I controesempi seguenti sono più istruttivi di qualsiasi regola astratta.

# Cattivo — troppo vago
{"description": "Retrieves data"}

# Buono — preciso e contestuale
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Cattivo — nessuna descrizione per il parametro
{"transaction_id": {"type": "string"}}

# Buono — descrizione con esempio
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Una buona descrizione indica in una frase cosa fa la funzione, specifica il formato atteso per ogni parametro e fornisce un esempio ogni volta che quel formato non è ovvio: T1001 è meglio di “ID transazione”. Quando i valori possibili sono limitati, non descriverli in prosa: dichiarali con enum. È l’unico modo per renderli vincolanti.

Punti chiave

  • Lo JSON Schema è il contratto tra il tuo codice e il modello: descrive le tue funzioni senza esporre il codice
  • Ogni strumento ha un name, una description e dei parameters tipizzati
  • I tipi supportati includono string, integer, number, boolean, array e object
  • L’elenco required distingue i parametri obbligatori da quelli opzionali
  • Le descrizioni precise con esempi migliorano significativamente l’accuratezza del modello