Schema di tool e funzioni

Il function calling consente al modello di chiedere al codice di eseguire un'azione. Ogni tool viene dichiarato con un nome, una descrizione, che indica quando usarlo, e un JSON Schema per i suoi parametri.

Il modello non esegue mai il codice; emette una richiesta di chiamata strutturata che il runtime inoltra. È lo schema a rendere analizzabili gli argomenti.

La definizione di un tool è una dichiarazione di funzionalità racchiusa in uno schema.

Quando sono disponibili molti tool, il modello sceglie principalmente in base alla descrizione. Scriva le descrizioni come regole decisionali:

• Indichi quando usarlo e quando non.
• Lo distingua dai tool simili.
• Menzioni le precondizioni necessarie.

Le descrizioni scadenti causano più spesso la selezione del tool sbagliato di quanto gli schemi scadenti causino errori negli argomenti.

Il function calling avviene su più turni. Il modello emette una chiamata, la si esegue, si aggiunge il risultato e il modello continua.

I modelli moderni possono richiedere più chiamate ai tool in un solo turno quando le azioni sono indipendenti. Il runtime dovrebbe iterare su tutti i tool_calls, eseguirli, idealmente in concorrenza, e restituire un messaggio tool per ogni tool_call_id.

Non presuma mai che ci sia una sola chiamata; esegua sempre un ciclo.

Controlli la selezione con tool_choice:

• auto — decide il modello.
• required — deve essere chiamato un tool.
• {name: ...} — forza un tool specifico.
• none — disabilita i tool per questo turno.

Forzare un tool specifico trasforma il function calling in una pura estrazione strutturata.

Anche con schemi rigorosi, tratti gli argomenti dei tool come input non attendibile. Li convalidi nuovamente rispetto allo schema e applichi le regole di business prima di interagire con sistemi reali, come database, pagamenti ed eliminazione di file.

Quando un tool fallisce, restituisca un errore strutturato come risultato del tool invece di generare un'eccezione. Il modello potrà quindi scusarsi, riprovare con argomenti corretti o scegliere un tool diverso.

Renda gli errori azionabili: includa un motivo e, quando è sicuro farlo, un suggerimento per il recupero.

Decine di tool riducono l'accuratezza della selezione e aumentano il costo in token, perché ogni schema è presente nel contesto a ogni turno. Possibili rimedi:

• Raggruppi le azioni correlate dietro un unico tool con un enum action.
• Esponga dinamicamente solo i tool pertinenti allo stato corrente.
• Usi il namespacing per ridurre la confusione tra tool simili.

Per le azioni distruttive, codifichi la sicurezza direttamente nello schema: richieda un campo di conferma esplicito, limiti gli intervalli e preferisca agli identificatori in testo libero gli enum o i pattern validati.

Consideri la selezione degli strumenti un comportamento misurabile. Costruisca un set di valutazione di prompt associati allo strumento e agli argomenti attesi, quindi verifichi che il modello scelga correttamente. Rilevi le regressioni quando riformula le descrizioni o aggiunge nuovi strumenti.

Un modello emette due tool_calls indipendenti in un'unica risposta dell'assistente. Che cosa deve fare il runtime?

Gli schemi degli strumenti e delle funzioni in pratica:

• Le descrizioni guidano la selezione; gli schemi determinano argomenti analizzabili.
• Scorra tutti i tool_calls; supporti l'esecuzione in parallelo.
• Controlli il comportamento con tool_choice; imponga uno strumento per la sola estrazione.
• Convalidi nuovamente gli argomenti; restituisca errori strutturati.
• Riduca al minimo la superficie degli strumenti e metta in sicurezza le azioni distruttive.

Successivamente: cicli di riparazione e validazione per i casi in cui l'output continui a essere errato.