Tool Calling per LLM — Come Dare Potere Reale ai Tuoi Agenti AI (con Esempi in Python)

Hai mai chiesto a un chatbot di inviare un'email, aggiornare un database o calcolare il prezzo scontato di un prodotto, e ti ha risposto «Non posso farlo»? Frustrante, vero. Il motivo è semplice: un Large Language Model (LLM) da solo sa solo generare testo. Per agire nel mondo reale — scrivere un record, chiamare un'API, mandare una notifica — ha bisogno di strumenti. Questa guida ti mostra come farlo, con codice funzionante e senza teoria astratta.

Noi, di Meteora Web, lavoriamo ogni giorno con l'AI per automazione e agenti. Tool calling è il punto di svolta: trasforma un LLM da chiacchierone a esecutore. Se gestisci un e-commerce o una PMI, significa niente più risposte vaghe, ma azioni reali.

Cos'è il Tool Calling e Perché è Critico per l'Automazione?

Tool calling (o function calling) è un meccanismo che permette a un LLM di dichiarare la sua intenzione di chiamare una funzione esterna. Il modello non esegue la funzione — genera un oggetto JSON con il nome e i parametri. Sta al tuo codice eseguirla e restituire il risultato. In pratica: il LLM decide cosa fare, tu fai accadere le cose.

Perché è critico? Perché senza tool calling, un agente AI è solo un generatore di testi: può scrivere «Ho aggiornato il database» ma non lo fa. Con tool calling, invece, quell'aggiornamento è reale. Lo vediamo nei progetti dei nostri clienti: ordini che partono, ticket che si chiudono, report che si generano. Il fatturato si misura in azioni, non in parole.

Come Funziona il Tool Calling negli LLM Moderni?

Il flusso è semplice e potente:

1. Definisci le funzioni disponibili (nome, descrizione, parametri in JSON Schema).
2. Includi queste definizioni nella richiesta all'LLM.
3. Il modello analizza il prompt e, se serve uno strumento, restituisce un oggetto tool_calls.
4. Il tuo codice esegue la funzione e restituisce il risultato come nuovo messaggio.
5. Il modello riceve il risultato e genera la risposta finale.

Funziona con OpenAI, Anthropic, Google Gemini e modelli open-source. L'importante è che la definizione sia chiara e i parametri precisi: un tool mal descritto produce chiamate sbagliate.

Esempio Pratico: Calcolatrice Integrata

Vediamo il codice che usa OpenAI API in Python. Assicurati di avere openai>=1.0 installato.

from openai import OpenAI
import json

client = OpenAI()

def calculate(operation, a, b):
    """Esegue un'operazione aritmetica."""
    if operation == "add":
        return a + b
    elif operation == "multiply":
        return a * b
    else:
        return "Operazione non supportata"

tools = [
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Esegue un'operazione aritmetica su due numeri",
            "parameters": {
                "type": "object",
                "properties": {
                    "operation": {"type": "string", "enum": ["add", "multiply"]},
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["operation", "a", "b"]
            }
        }
    }
]

messages = [{"role": "user", "content": "Quanto fa 123 per 456?"}]
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=tools
)

if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    result = calculate(**args)
    messages.append(response.choices[0].message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps({"result": result})
    })
    final_response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages
    )
    print(final_response.choices[0].message.content)

Provalo: l'LLM capisce che serve una moltiplicazione, chiama calculate e riceve il risultato. Puoi estendere questo schema a qualsiasi API.

Quali Strumenti Dare al Tuo LLM?

Non tutti gli strumenti sono utili. Scegli in base al contesto. Ecco i più comuni nei progetti che seguiamo:

• Ricerca interna (RAG): query su un DB vettoriale per documenti aziendali.
• API esterne: meteo, spedizioni, pagamenti.
• CRUD su database: creare un lead, aggiornare un ordine.
• Invio email o notifiche: conferme, alert.
• Calcoli custom: IVA, sconti, rate.

Attenzione alla sicurezza: non dare mai DELETE * FROM clienti a un LLM non verificato. Limitiamo i permessi e validiamo sempre l'output. Noi lo gestiamo con un layer di autorizzazione prima di eseguire la funzione.

Errori Comuni e Come Evitarli nella Chiamata a Strumenti

Abbiamo visto (e commesso) errori classici:

1. Descrizioni vaghe: il modello chiama lo strumento sbagliato. Usa descrizioni dettagliate: «Esegue la moltiplicazione di due numeri a e b, restituisce il prodotto».
2. Parametri mancanti: se un campo non è required, il modello può saltarlo. Metti tutto ciò che serve come obbligatorio.
3. Gestione errori assente: se la funzione lancia eccezione, il loop si rompe. Restituisci un messaggio d'errore strutturato e lascia che il modello decida come gestirlo.
4. Troppi strumenti: più di 10-15 strumenti confondono il modello. Raggruppa o usa routing gerarchico.

Un caso reale: un cliente aveva uno strumento per «inviare email» senza limiti di destinatario. L'LLM ha inviato 500 email a caso. Ora mettiamo un limite e una conferma umana.

Tool Calling vs RAG: Differenze e Quando Usarli Insieme?

RAG (Retrieval-Augmented Generation) e tool calling non sono in competizione. RAG porta conoscenza, tool calling porta azione. Un agente che risponde a domande sul catalogo usa RAG; un agente che aggiorna lo stock dopo un acquisto usa tool calling. In molti progetti li combiniamo: l'LLM cerca documenti (RAG) e poi esegue comandi (tool calling).

La vera scelta è: l'agente deve solo rispondere o anche agire? Se solo rispondere, RAG basta. Se deve agire, serve tool calling.

Cosa Fare Adesso

Ecco tre azioni immediate per iniziare con tool calling:

1. Scrivi un tool semplice: una funzione che restituisce l'ora corrente o un dato fittizio. Integra con OpenAI API come nell'esempio sopra.
2. Aggiungi uno strumento reale: connettiti a un'API di test (es. Open-Meteo per il meteo). Vedi se l'LLM chiama correttamente e usa il risultato.
3. Verifica la sicurezza: imposta un whitelist di azioni permesse e un limite per chiamata. Non eseguire mai funzioni su input utente non filtrato.

Noi, di Meteora Web, usiamo tool calling quotidianamente per automatizzare flussi di lavoro: dalla gestione ordini all'invio di preventivi. Il prossimo passo? Agenti multi-tool che collaborano. Se vuoi approfondire, dai un'occhiata al nostro pillar sull'AI agentica.

Leggi anche come Morgan Stanley ha dimezzato i tempi di riconciliazione usando agenti AI con tool calling e come poche aziende monitorano davvero i propri modelli AI.