Il tool calling è il modo in cui un modello linguistico agisce sul mondo: chiede al tuo codice di cercare un dato, lanciare una query o modificare un file, e poi usa il risultato.
Come funziona
La guida di OpenAI descrive un ciclo tra la tua app e il modello:
- Invia gli strumenti. La richiesta elenca le funzioni con un nome, una descrizione e un JSON Schema per gli argomenti.
- Ricevi una chiamata a uno strumento. Se il modello ha bisogno di uno strumento, restituisce il nome della funzione e gli argomenti JSON al posto di una risposta finale.
- Eseguila. Il tuo codice esegue la funzione. La guida di OpenAI colloca questo passaggio “the application side” (traduzione: dal lato dell’applicazione); il modello non esegue mai codice da solo.
- Restituisci il risultato con l’ID di chiamata corrispondente.
- Ricevi la risposta, oppure un’altra chiamata a uno strumento. Ripeti quanto serve.
Nel formato Chat Completions, la definizione di uno strumento è fatta così:
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up an order by ID",
"parameters": {
"type": "object",
"properties": { "order_id": { "type": "string" } },
"required": ["order_id"]
}
}
}
La risposta ha finish_reason: "tool_calls" e un elenco tool_calls. Ogni voce ha un id, il nome della funzione e arguments come stringa JSON. Aggiungi un messaggio con role: "tool", lo stesso tool_call_id e il risultato, poi richiami l’API.
Perché è importante
- Agenti. Agenti di coding, bot di assistenza e assistenti per i dati sono per lo più cicli di chiamate a strumenti.
- Costo. Ogni andata e ritorno è una nuova richiesta che rimanda conversazione, definizioni degli strumenti e loro risultati come token di input. Nei cicli lunghi diventano importanti l’input in cache e un ordine stabile degli strumenti.
- Sicurezza. Gli argomenti arrivano dal modello. Validali prima di eseguire qualsiasi cosa che modifica dati o spende soldi.
Per una risposta che deve rispettare uno schema ma non richiede alcuna funzione, lo strumento più semplice è l’output strutturato.
Su BroadNet Inference
La documentazione di BroadNet indica il tool calling per GLM 5.3 e Qwen3.8 27B, entrambi con output strutturato e ragionamento. Non dichiara il supporto agli strumenti per DeepSeek V4.1 Flash né per BroadNet Gemma 4 VL 26B. Prova il tuo ciclo di strumenti sul modello che intendi mettere in produzione.
Entrambi i modelli indicati ragionano prima di rispondere, e il ragionamento conta in max_tokens, quindi lascia margine, altrimenti una chiamata a uno strumento può essere troncata. Vedi token di ragionamento. Per gli strumenti da agente che usano un proprio formato degli strumenti, vedi la guida a Cline e la guida al Vercel AI SDK.
Errori comuni
- Trattare
argumentscome un oggetto. Arriva come stringa JSON: decodificala e gestisci gli errori. - Dimenticare il
tool_call_id. Senza, il modello non riesce ad abbinare i risultati alle chiamate.