Il tool calling, chiamato anche function calling, permette a un modello AI di richiedere l’uso di una funzione esterna: cercare un ordine, interrogare un database, creare una bozza di ticket o calcolare un preventivo. È il passaggio che trasforma un chatbot capace di scrivere in un componente capace di collaborare con applicazioni reali.
La distinzione più importante è questa: il modello propone la chiamata, ma normalmente non esegue la funzione. Restituisce nome e argomenti strutturati; il codice dell’applicazione controlla identità, permessi e parametri, decide se procedere e rimanda il risultato al modello. Confondere proposta ed esecuzione porta a integrazioni fragili e pericolose.
Indice
- Che cos’è il tool calling
- Come funziona passo dopo passo
- Anatomia di uno strumento
- Esempio pratico con Ollama
- Tool calling, output strutturato, RAG, MCP e agenti
- Come progettare tool affidabili
- Sicurezza e approvazione umana
- Test, errori e monitoraggio
- FAQ
Che cos’è il tool calling
Un modello linguistico può spiegare come controllare un ordine, ma non conosce automaticamente lo stato aggiornato nel gestionale. Con il tool calling l’applicazione gli presenta una o più funzioni disponibili, descritte tramite un contratto strutturato. Il modello può scegliere quella pertinente e compilare gli argomenti.
Per esempio, davanti alla domanda «A che punto è l’ordine 1842?», il modello potrebbe produrre una richiesta simile:
{
"name": "orders_get_status",
"arguments": {
"order_id": "1842"
}
}Questa struttura non è ancora lo stato dell’ordine e non autorizza automaticamente l’operazione. Il backend deve verificare che la funzione esista, che l’utente possa vedere quell’ordine e che l’identificativo sia valido. Solo dopo interroga il sistema e restituisce un risultato, per esempio {"status":"in preparazione"}. Il modello lo trasforma infine in una risposta leggibile.
Il meccanismo è supportato, con formati e SDK differenti, dalle principali API cloud e da runtime locali come Ollama. Le denominazioni cambiano, ma il ciclo applicativo rimane simile.
Come funziona passo dopo passo
Un’implementazione completa comprende normalmente sette passaggi.
- Definizione: l’applicazione descrive nome, scopo e parametri del tool.
- Richiesta: invia al modello messaggi e strumenti disponibili.
- Selezione: il modello risponde direttamente oppure propone una chiamata.
- Validazione: il backend controlla schema, valori, identità, permessi e policy.
- Esecuzione: il codice richiama API, database o processo autorizzato.
- Risultato: l’applicazione rimanda al modello l’esito associato alla chiamata.
- Risposta o nuovo passo: il modello spiega il risultato o propone un altro tool.
OpenAI, Anthropic, Google e Ollama documentano questo scambio in modi leggermente diversi. In tutti i casi, per i tool gestiti dal cliente, l’esecuzione appartiene all’applicazione e non va delegata ciecamente al testo generato.
Chiamata singola e ciclo agentico
Una chiamata singola può bastare per leggere un dato. Un agente AI ripete invece il ciclo, utilizzando un risultato per decidere il passo successivo. Questo aumenta la capacità, ma anche latenza, costi e superficie di rischio. È necessario definire un numero massimo di iterazioni, timeout e condizioni di arresto.
Anatomia di uno strumento
Un tool contiene almeno:
- un nome univoco e comprensibile;
- una descrizione che chiarisce quando usarlo;
- uno schema degli argomenti;
- l’elenco dei campi obbligatori;
- eventuali valori ammessi, limiti e formati.
Ecco un contratto semplificato per preparare una richiesta di assistenza senza inviarla:
{
"name": "tickets_prepare_draft",
"description": "Prepara una bozza di ticket; non effettua l'invio",
"parameters": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": ["accesso", "hardware", "software", "rete"]
},
"summary": {
"type": "string",
"maxLength": 300
},
"priority": {
"type": "string",
"enum": ["bassa", "normale", "alta"]
}
},
"required": ["category", "summary"]
}
}Il nome separa il dominio dall’azione; la descrizione specifica che si produce soltanto una bozza; gli enum limitano le scelte. Il backend deve comunque ripetere la validazione: lo schema presentato al modello migliora la precisione, ma non è un controllo di sicurezza sufficiente.
Esempio pratico con Ollama
Ollama supporta chiamate singole, parallele e cicli multi-turno. Questo esempio locale espone una funzione Python che restituisce lo stato di un ordine da un dizionario dimostrativo.
from ollama import chat
def get_order_status(order_id: str) -> str:
"""Restituisce lo stato di un ordine autorizzato."""
orders = {"1842": "in preparazione", "1843": "spedito"}
return orders.get(order_id, "ordine non trovato")
messages = [
{"role": "user", "content": "A che punto è l'ordine 1842?"}
]
response = chat(
model="qwen3",
messages=messages,
tools=[get_order_status]
)
messages.append(response.message)
if response.message.tool_calls:
call = response.message.tool_calls[0]
order_id = call.function.arguments["order_id"]
# Qui vanno autenticazione, autorizzazione e validazione.
result = get_order_status(order_id)
messages.append({
"role": "tool",
"tool_name": call.function.name,
"content": result
})
final = chat(model="qwen3", messages=messages, tools=[get_order_status])
print(final.message.content)In produzione il dizionario sarebbe sostituito da un servizio. Le credenziali del gestionale non devono essere inserite nel prompt né restituite al modello: restano nel backend o in un gestore di segreti. La guida Come installare Ollama aiuta a predisporre il runtime locale.
Tool calling, output strutturato, RAG, MCP e agenti
Questi concetti vengono spesso sovrapposti, ma risolvono problemi diversi.
| Concetto | Scopo principale | Esegue un’azione? |
|---|---|---|
| Output strutturato | Ottenere dati in uno schema preciso | No |
| Tool calling | Chiedere a un’applicazione di usare una funzione | Soltanto dopo esecuzione del backend |
| RAG | Recuperare contenuti pertinenti da una base documentale | Normalmente legge dati |
| MCP | Standardizzare esposizione e scoperta di risorse e tool | Dipende dai tool esposti |
| Agente | Pianificare e concatenare più passaggi | Può farlo entro i limiti concessi |
Usare JSON non significa automaticamente usare tool calling. Se serve soltanto classificare un testo in campi, è preferibile un output strutturato. Se occorre leggere dati aziendali aggiornati, può bastare un sistema RAG o una funzione di sola lettura. Se si vogliono connettori riutilizzabili tra client differenti, entra in gioco il Model Context Protocol.
Come progettare tool affidabili
Una responsabilità chiara
Un tool dovrebbe svolgere un compito delimitato. orders_get_status è più controllabile di execute_business_action. Evitare strumenti generici come “esegui comando shell”, “interroga qualsiasi URL” o “esegui SQL”: rendono difficile applicare policy e contenere errori.
Separare lettura e scrittura
Non combinare customer_read e customer_update nella stessa funzione se il caso d’uso richiede soltanto consultazione. Separare azioni consente identità e autorizzazioni differenti e riduce il danno possibile.
Descrizioni e schemi non ambigui
Specificare quando usare il tool, cosa non fa e quali unità o formati accetta. Preferire enum, campi obbligatori e limiti di lunghezza. Per date, importi e identificativi adottare formati canonici e validarli nel codice.
Restituire risultati essenziali
Un tool non dovrebbe riversare intere tabelle o documenti se bastano pochi campi. Ridurre il risultato limita token, latenza e dati esposti. L’inference va misurata sull’intera catena, incluse chiamate esterne e tempi di coda.
Sicurezza e approvazione umana
Il modello deve essere trattato come un componente non affidabile che propone input, non come un’identità autorizzata. Le difese principali sono applicative.
Controlli minimi
- autenticare l’utente fuori dal modello;
- autorizzare ogni operazione sul backend;
- validare nuovamente tutti gli argomenti;
- usare identità con privilegi minimi;
- conservare i segreti fuori dal prompt;
- applicare allowlist, timeout e limiti di frequenza;
- registrare richiesta, decisione, esito e attore;
- rendere idempotenti le operazioni ripetibili;
- richiedere conferma per azioni irreversibili o economiche.
OWASP definisce Excessive Agency il rischio di concedere funzionalità, permessi o autonomia superiori a quelli necessari. Una funzione che deve leggere la posta non dovrebbe anche poterla inviare o cancellare. La checklist Agenti AI: sicurezza e controllo approfondisce privilegi minimi, approvazioni, audit e arresto.
Il contenuto del tool non è attendibile
Una pagina web, un’email o un documento recuperato può contenere istruzioni malevole. Il risultato deve essere considerato dato non fidato: va separato dalle istruzioni di sistema, filtrato e limitato. RAG e fine-tuning non eliminano il rischio di prompt injection.
Conferma a due fasi
Per invii, modifiche, acquisti o cancellazioni è utile dividere il processo:
prepare_*crea una bozza con anteprima;- l’utente o una policy approva;
execute_*riceve un identificativo firmato e applica l’azione.
Il modello non deve poter inventare l’approvazione. Il backend verifica stato, scadenza e identità prima dell’esecuzione.
Test, errori e monitoraggio
Un tool va provato anche quando il modello sbaglia.
| Caso di test | Comportamento atteso |
|---|---|
| Parametro mancante | Rifiuto controllato e richiesta di chiarimento |
| Identificativo di altro utente | Accesso negato senza esporre dati |
| Servizio non disponibile | Errore sintetico, retry limitato o passaggio umano |
| Doppia chiamata | Nessun effetto duplicato grazie all’idempotenza |
| Tool inesistente | Nessuna esecuzione e log dell’anomalia |
| Contenuto con prompt injection | Dato trattato come non affidabile |
| Operazione ad alto impatto | Anteprima e approvazione obbligatoria |
In produzione conviene misurare frequenza delle chiamate, tasso di successo, errori di schema, rifiuti di autorizzazione, timeout, costi e approvazioni. I log devono consentire di ricostruire chi ha chiesto cosa, quale versione del tool è stata usata e quale risultato è stato prodotto, senza registrare segreti inutili.
Per workflow semplici, n8n con AI può orchestrare chiamate, approvazioni e gestione degli errori. Anche in un ambiente visuale, però, credenziali e permessi restano responsabilità dell’architettura.
Errori comuni
- credere che lo schema sostituisca autorizzazione e validazione;
- dare al modello un tool generico e privilegiato;
- inserire password o token API nelle istruzioni;
- eseguire subito operazioni irreversibili;
- fidarsi del testo restituito da documenti o servizi esterni;
- non gestire timeout, doppie chiamate e retry;
- offrire decine di strumenti quasi identici;
- ignorare log, versioni e indicatori di qualità.
FAQ
Il modello esegue direttamente la funzione?
Per i tool definiti dall’applicazione, normalmente no: produce una chiamata strutturata. Il backend la valida ed esegue. Alcuni fornitori offrono anche strumenti gestiti sui propri server, con un modello operativo diverso.
Tool calling e function calling sono la stessa cosa?
Nell’uso comune sì. “Tool” è un termine più ampio: può includere funzioni personalizzate e strumenti gestiti come ricerca, esecuzione di codice o accesso a file.
Serve MCP per usare il tool calling?
No. Si possono definire funzioni direttamente tramite l’API del modello. MCP è utile quando si vuole standardizzare la connessione e riutilizzare strumenti e risorse tra client compatibili.
Il tool calling funziona con modelli locali?
Sì, se modello e runtime lo supportano. Ollama documenta chiamate singole, parallele, multi-turno e streaming. La qualità nella scelta del tool va comunque verificata sul modello specifico.
Come gestire cancellazioni e pagamenti?
Con tool separati, privilegi minimi, anteprima, approvazione umana esplicita, idempotenza, limiti, audit e possibilità di interrompere il processo.
Conclusioni
Il tool calling crea un ponte tra linguaggio naturale e sistemi aziendali, ma non trasferisce al modello l’autorità dell’applicazione. Il modello propone; il codice valida, autorizza ed esegue.
Un progetto affidabile parte da strumenti piccoli, schemi chiari e operazioni di sola lettura. Aggiunge poi approvazioni e capacità di scrittura soltanto quando test, identità, log e procedure di recupero sono pronti. È questa separazione a rendere l’integrazione utile senza trasformare un errore probabilistico in un’azione reale incontrollata.
Vuoi ricevere guide pratiche su AI locale, integrazioni e governance? Iscriviti gratuitamente alla newsletter di BASI DI AI.
