---
title: "Tool calling con modelli aperti: schemi, retry, codice"
description: "Function calling su modelli aperti compatibili con OpenAI: schemi, chiamate parallele, i cinque modi in cui falliscono e un ciclo Python che valida e riprova."
url: https://broadrouter.com/it/blog/tool-calling-open-models/
lang: it
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/blog/tool-calling-open-models/) (aggiornato il 2026-11-16).

# Tool calling con modelli aperti: schemi, chiamate parallele, retry

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato 2026-11-14 · Aggiornato 2026-11-16

I modelli aperti sulle API compatibili con OpenAI usano lo stesso formato tools e tool\_calls di OpenAI. Tieni gli schemi piccoli e piatti, tratta gli argomenti come stringhe JSON, validali prima di eseguire qualsiasi cosa e restituisci gli errori al modello come risultati dei tool, così può riprovare. Limita i passaggi. Su BroadNet, GLM 5.3 e Qwen3.8 27B dichiarano il supporto ai tool.

## Punti chiave

-   Il formato è lo stesso di OpenAI: una lista tools in ingresso, tool\_calls in uscita, poi un messaggio con ruolo tool per ogni tool\_call\_id.
-   Gli argomenti arrivano come stringa JSON. La documentazione di vLLM avverte che, quando estrae le chiamate dal testo grezzo, «may occasionally be malformed or violate the function’s parameter schema» (traduzione: possono occasionalmente essere malformate o violare lo schema dei parametri della funzione).
-   Valida ogni chiamata, rimanda gli errori come risultati dei tool e limita sia i retry sia i passaggi totali.
-   Meno tool, e più piatti, funzionano meglio. OpenAI suggerisce meno di 20 funzioni all’inizio di un turno.
-   Su BroadNet Inference usa GLM 5.3 o Qwen3.8 27B per il tool calling; prova DeepSeek V4.1 Flash prima di farci affidamento.

**In questa pagina**

1.  Come funziona il tool calling su un’API compatibile con OpenAI?
2.  Come scrivere gli schemi dei tool?
3.  E le chiamate parallele ai tool?
4.  Perché le chiamate ai tool falliscono?
5.  Un ciclo di tool che valida e riprova
6.  Quali modelli BroadNet supportano il tool calling?
7.  Dove si inserisce BroadNet Inference

Il [tool calling](https://broadrouter.com/it/glossary/tool-calling/) è ciò che trasforma un modello in un agente. Con i modelli aperti su un’[API compatibile con OpenAI](https://broadrouter.com/it/glossary/openai-compatible-api/), 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?

1.  Invii `messages` più una lista `tools`. Ogni tool ha un nome, una descrizione e uno JSON Schema per i suoi argomenti.
2.  Il modello risponde con `finish_reason: "tool_calls"` e una lista `tool_calls`. Ogni voce ha un `id`, un nome di funzione e `arguments` come **stringa JSON**.
3.  Il tuo codice esegue ogni chiamata e aggiunge un messaggio `role: "tool"` per chiamata, con il `tool_call_id` corrispondente.
4.  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_file` o `search_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](https://broadrouter.com/it/blog/agent-token-budget/).
-   **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](https://broadrouter.com/tools/json-schema-generator/) 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: false` e ogni campo in `required`, con `null` come tipo per quelli facoltativi. Non tutti i provider impongono `strict`, 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](https://broadrouter.com/it/glossary/reasoning-tokens/). GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il thinking conta in [`max_tokens`](https://broadrouter.com/it/glossary/max-tokens/). [Perché le risposte tornano vuote o tagliate](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/) spiega quanto margine lasciare.

## Un ciclo di tool che valida e riprova

```python
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:

1.  **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à.
2.  **Il ciclo è limitato.** `max_steps` ferma un modello che continua a chiamare tool senza fare progressi.
3.  **I retry di trasporto sono separati.** `max_retries` sul client gestisce 429 e 5xx. Gli argomenti sbagliati si gestiscono nel ciclo. Non mescolare le due cose; vedi [errori e retry](https://broadrouter.com/it/guides/errors-and-retries/).

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](https://broadrouter.com/it/blog/long-running-agents-timeouts-retries/).

## Quali modelli BroadNet supportano il tool calling?

| Modello | Tool dichiarati | Contesto | Note |
| --- | --- | --- | --- |
| [GLM 5.3](https://broadrouter.com/it/models/glm-5.3/) | Sì | 1.048.576 | Anche output strutturato |
| [Qwen3.8 27B](https://broadrouter.com/it/models/qwen3.8-27b/) | Sì | 262.144 | Anche input di immagini |
| [DeepSeek V4.1 Flash](https://broadrouter.com/it/models/deepseek-v4.1-flash/) | Non dichiarato | 1.048.576 | Input di immagini; prova i tool prima di farci affidamento |
| [Gemma 4 VL 26B](https://broadrouter.com/it/models/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](https://broadrouter.com/compare/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](https://broadrouter.com/it/blog/structured-output-json-schema/) è 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](https://broadrouter.com/it/guides/openai-python-sdk/). I prezzi per token sono nella [pagina dei prezzi](https://broadrouter.com/it/pricing/). 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.

Strumenti gratuiti sul tema (in inglese)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Strumenti gratuiti (in inglese)](https://broadrouter.com/tools/)

## Termini in questo articolo

[Tool calling (chiamata di strumenti)](https://broadrouter.com/it/glossary/tool-calling/)

Il tool calling, detto anche function calling, è una funzionalità delle API LLM in cui il modello restituisce una richiesta strutturata di eseguire una funzione definita dallo sviluppatore, con argomenti JSON. L’applicazione esegue la funzione e rimanda il risultato; il modello non esegue mai codice da solo.

[Token](https://broadrouter.com/it/glossary/token/)

Un token è l’unità di testo che un modello linguistico legge e scrive: una parola, una parte di parola, un segno di punteggiatura o una sequenza di byte prodotta dal tokenizer del modello. Le API LLM contano, limitano e di solito fatturano l’uso in token.

[vLLM](https://broadrouter.com/it/glossary/vllm/)

vLLM è una libreria open source per l’inferenza e il serving di LLM, sviluppata inizialmente allo Sky Computing Lab di UC Berkeley. Gestisce la memoria della KV cache con PagedAttention, raggruppa in batch continuo le richieste in arrivo, supporta molti formati di quantizzazione ed espone un server HTTP compatibile OpenAI.

[AI multimodale (multimodal AI)](https://broadrouter.com/it/glossary/multimodal/)

L’AI multimodale è un modello o un sistema che lavora con più di un tipo di dato, come testo, immagini, video e audio. Un modello multimodale può leggere insieme una foto e una domanda, oppure ricevere parlato e rispondere in testo. Il tipo più comune è il modello vision-language.

[API compatibile con OpenAI](https://broadrouter.com/it/glossary/openai-compatible-api/)

Un’API compatibile con OpenAI è un’API HTTP che accetta gli stessi formati di richiesta e di risposta dell’API di OpenAI, come POST /v1/chat/completions, così SDK e strumenti di OpenAI possono usarla cambiando solo base URL, chiave API e nome del modello.

[JSON Schema](https://broadrouter.com/it/glossary/json-schema/)

JSON Schema è un vocabolario, scritto in JSON, per descrivere e validare la struttura dei dati JSON: tipi, campi obbligatori, valori ammessi e annidamento. La versione attuale è la 2020-12. Le API LLM lo usano per definire i parametri dei tool e la forma esatta che un output strutturato deve seguire.

[Output strutturato (structured output)](https://broadrouter.com/it/glossary/structured-output/)

L’output strutturato è una funzionalità delle API LLM che vincola la risposta di un modello a un formato indicato dallo sviluppatore, di solito un JSON Schema, così il codice può interpretarla in modo affidabile. È più rigoroso della JSON mode, che garantisce un JSON valido ma non una struttura precisa.

[Chat Completions API](https://broadrouter.com/it/glossary/chat-completions-api/)

La Chat Completions API è l’endpoint HTTP di OpenAI, POST /v1/chat/completions, che riceve il nome di un modello e una lista di messaggi con un ruolo e restituisce il messaggio successivo del modello. La forma della sua richiesta e risposta è diventata il formato comune che riusano provider e SDK compatibili con OpenAI.

## Domande frequenti

### I modelli aperti supportano il function calling?

Molti sì, ma il supporto dipende dal modello e da come il provider lo serve. Su BroadNet Inference la documentazione indica il tool calling per GLM 5.3 e Qwen3.8 27B. Non lo indica per DeepSeek V4.1 Flash né per Gemma 4 VL 26B.

### Perché gli argomenti delle mie chiamate ai tool sono JSON non valido?

Se il server non vincola la decodifica, gli argomenti vengono generati come testo e parsati dopo. La documentazione di vLLM dice che gli argomenti estratti dal testo grezzo possono occasionalmente essere malformati. Intercetta l’errore di parsing e rimandalo come risultato del tool, così il modello può correggersi.

### Come disattivo le chiamate parallele ai tool?

Nel formato OpenAI imposta parallel\_tool\_calls a false. Così il modello è limitato a zero o una chiamata per turno. Verifica che il tuo provider rispetti il campo.

### Perché il modello risponde con del testo invece di chiamare un tool?

Con tool\_choice auto decide il modello. Imposta tool\_choice a required, o a una funzione specifica, quando la chiamata è obbligatoria. Controlla anche che la descrizione del tool dica quando usarlo.

### Perché la mia chiamata al tool è tagliata?

I modelli di ragionamento contano il thinking in max\_tokens. Un limite basso può chiudere la risposta a metà degli argomenti. Controlla finish\_reason e alza max\_tokens.

## Continua a leggere

-   [OpenClaw e Hermes Agent con un modello economico: setup e costi](https://broadrouter.com/it/blog/openclaw-hermes-agent-cheap-model/)
-   [JSON mode o json\_schema: output strutturato che regge in produzione](https://broadrouter.com/it/blog/structured-output-json-schema/)
-   [Server MCP con modelli compatibili con OpenAI, di qualsiasi provider](https://broadrouter.com/it/blog/mcp-with-openai-compatible-models/)
-   [Agenti di lunga durata: timeout, retry e checkpoint che reggono](https://broadrouter.com/it/blog/long-running-agents-timeouts-retries/)
-   [Budget di token di un agente: dove vanno i token di un ciclo](https://broadrouter.com/it/blog/agent-token-budget/)
-   [Hardware GPU e serving di BroadNet, come li descrive BroadNet](https://broadrouter.com/it/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache delle risposte delle API LLM: una cache esatta in Python](https://broadrouter.com/it/blog/cache-llm-responses-cut-cost/)
-   [Guida: Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)
-   [Guida: Usare l’OpenAI Agents SDK con BroadNet Inference](https://broadrouter.com/it/guides/openai-agents-sdk-custom-provider/)
-   [Guida: Perché un modello di ragionamento restituisce una risposta vuota](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/)
-   [Guida: Codici di errore di BroadNet Inference e quando ritentare](https://broadrouter.com/it/guides/errors-and-retries/)

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-tool-calling-open-models&utm_content=page-cta) ·

**Fonti**

-   [OpenAI, guida al function calling (verifica del 2026-11-14)](https://developers.openai.com/api/docs/guides/function-calling)
-   [Documentazione di vLLM, tool calling (verifica del 2026-11-14)](https://docs.vllm.ai/en/latest/features/tool_calling/)
-   [Riferimento API di BroadNet Inference, modelli (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-tool-calling-open-models&utm_content=sources#models)
