Il tool calling è ciò che trasforma un modello in un agente. Con i modelli aperti su un’API compatibile con OpenAI, il formato della richiesta è lo stesso che useresti con OpenAI. Cambiano la frequenza con cui le cose vanno storte e ciò che il server fa per evitarlo. Questo articolo copre il formato, come scrivere schemi che i modelli aperti gestiscono bene, le chiamate parallele, i cinque fallimenti che vedrai davvero e un ciclo Python che li supera.
Come funziona il tool calling su un’API compatibile con OpenAI?
- Invii
messagespiù una listatools. Ogni tool ha un nome, una descrizione e uno JSON Schema per i suoi argomenti. - Il modello risponde con
finish_reason: "tool_calls"e una listatool_calls. Ogni voce ha unid, un nome di funzione eargumentscome stringa JSON. - Il tuo codice esegue ogni chiamata e aggiunge un messaggio
role: "tool"per chiamata, con iltool_call_idcorrispondente. - Chiami di nuovo l’API. Il modello risponde o chiede altri tool.
Il modello non esegue mai nulla. È il tuo codice a decidere cosa eseguire.
Come scrivere gli schemi dei tool?
I modelli aperti seguono in modo più affidabile gli schemi semplici. Queste regole vengono dalla guida di OpenAI e da ciò che tende a rompersi:
- Dai ai tool nomi d’azione, come
read_fileosearch_code, e scrivi nella descrizione quando usare ciascuno. - Tieni la lista corta. La guida di OpenAI presenta le meno di 20 funzioni all’inizio di un turno come un suggerimento, non una regola rigida. Ogni schema viene anche inviato a ogni chiamata; vedi il budget di token di un agente.
- Preferisci argomenti piatti. Stringhe, numeri, booleani ed enum. Evita annidamenti profondi e oggetti a forma libera.
- Usa gli enum per le scelte fisse, così il modello non può inventare un valore. Il generatore di JSON schema trasforma un oggetto di argomenti di esempio in uno schema piatto da incollare in
parameters. - Segna i campi obbligatori. La modalità strict di OpenAI richiede
additionalProperties: falsee ogni campo inrequired, connullcome tipo per quelli facoltativi. Non tutti i provider impongonostrict, quindi valida comunque.
E le chiamate parallele ai tool?
Un modello può restituire più voci in tool_calls nello stesso turno, per esempio tre letture di file. Esegui in parallelo le chiamate indipendenti e restituisci un risultato per ogni tool_call_id, in qualsiasi ordine. Se i tuoi tool hanno effetti collaterali che dipendono l’uno dall’altro, imposta parallel_tool_calls: false; la guida di OpenAI dice che così il modello è limitato a zero o una chiamata per turno. Verifica che il tuo provider lo rispetti.
Perché le chiamate ai tool falliscono?
| Fallimento | Cosa vedi | Soluzione |
|---|---|---|
| Argomenti malformati | json.loads solleva un’eccezione |
Restituisci l’errore di parsing come risultato del tool; riprova |
| Schema non rispettato | Campo mancante, tipo sbagliato, enum inventato | Valida; restituisci l’errore di validazione |
| Tool sconosciuto | Un nome che non hai mai definito | Restituisci “unknown tool, available: …” |
| Nessuna chiamata quando serve | Una risposta testuale | tool_choice: "required" o una funzione specifica |
| Chiamata tagliata | finish_reason: "length" |
Alza max_tokens; il ragionamento lo condivide |
I primi due sono attesi, non rari. La documentazione di vLLM sul tool calling dice che in modalità auto, a meno che un tool non imposti strict: true (o il server imponga un livello minimo di rigore) e il parser del modello supporti i vincoli, «vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.» (traduzione: vLLM estrae le chiamate ai tool dal testo grezzo, quindi gli argomenti possono occasionalmente essere malformati o violare lo schema dei parametri della funzione). Una funzione specifica usa il backend structured-outputs di vLLM. Il tuo provider può servire i modelli in modo diverso, quindi considera la validazione obbligatoria.
L’ultima riga sorprende chi usa i modelli di ragionamento. GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il thinking conta in max_tokens. Perché le risposte tornano vuote o tagliate spiega quanto margine lasciare.
Un ciclo di tool che valida e riprova
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up one order by its ID. Use when the user asks where an order is.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}
def run_call(call):
name = call.function.name
if name not in IMPL:
return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
try:
args = json.loads(call.function.arguments or "{}")
validate(args, SCHEMAS[name])
except (json.JSONDecodeError, ValidationError) as e:
return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
return str(IMPL[name](**args))
def agent(messages, max_steps=8):
for _ in range(max_steps):
r = client.chat.completions.create(model=MODEL, messages=messages,
tools=TOOLS, max_tokens=4000)
msg = r.choices[0].message
if r.choices[0].finish_reason == "length":
raise RuntimeError("Output limit reached; raise max_tokens")
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": call.id,
"content": run_call(call)})
raise RuntimeError("Step limit reached")
Qui contano tre scelte di design:
- Gli errori tornano al modello come risultati dei tool. Il modello vede cosa non andava e di solito lo corregge al turno successivo. Sollevare un’eccezione butta via questa possibilità.
- Il ciclo è limitato.
max_stepsferma un modello che continua a chiamare tool senza fare progressi. - I retry di trasporto sono separati.
max_retriessul client gestisce 429 e 5xx. Gli argomenti sbagliati si gestiscono nel ciclo. Non mescolare le due cose; vedi errori e retry.
Per i tool con effetti collaterali, come l’invio di un’email, aggiungi una chiave di idempotenza così un passaggio ripetuto non agisce due volte. Lo spiega agenti a lunga esecuzione.
Quali modelli BroadNet supportano il tool calling?
| Modello | Tool dichiarati | Contesto | Note |
|---|---|---|---|
| GLM 5.3 | Sì | 1.048.576 | Anche output strutturato |
| Qwen3.8 27B | Sì | 262.144 | Anche input di immagini |
| DeepSeek V4.1 Flash | Non dichiarato | 1.048.576 | Input di immagini; prova i tool prima di farci affidamento |
| Gemma 4 VL 26B | Non dichiarato | 32.768 | Non adatto ai cicli di tool |
Per scegliere tra i due modelli con i tool, vedi GLM 5.3 vs Qwen3.8 27B. Quando la risposta finale deve avere una certa forma ma non serve eseguire nessuna funzione, l’output strutturato è più semplice di un tool.
Dove si inserisce BroadNet Inference
BroadNet Inference serve GLM 5.3 e Qwen3.8 27B con il tool calling dichiarato, tramite il formato standard chat completions, quindi il ciclo qui sopra gira senza modifiche con l’SDK Python di OpenAI. I prezzi per token sono nella pagina dei prezzi. Non offre tool lato server come la ricerca web o l’esecuzione di codice, e la sua documentazione non indica il tool calling per DeepSeek V4.1 Flash, il modello dei piani illimitati. Per un agente che usa molto i tool, usa GLM 5.3 o Qwen3.8 27B a token. Se vuoi comunque il piano flat, verifica con un’ora Meteor a $1 che DeepSeek V4.1 Flash chiami i tuoi tool in modo affidabile prima di comprare un mese.
