Vai al contenuto
TokIQ
Agenti

Tool calling negli LLM: function calling e agenti AI

Come funziona il tool calling degli LLM, come scrivere descrizioni che i modelli usano bene, come girano e si fermano i cicli degli agenti e gli errori tipici.

TokIQ Editorial6 min di lettura
In questo articolo
  1. Che aspetto ha la definizione di uno strumento?
  2. Come si scrivono descrizioni che il modello usa correttamente?
  3. Come funziona il ciclo di un agente?
  4. Come deve decidere un agente quando fermarsi?
  5. Quali sono gli errori più comuni degli agenti?
  6. E la sicurezza?
  7. Ti serve davvero un agente?
  8. Dove si colloca MCP?

Il tool calling (o function calling) permette a un modello linguistico di chiedere alla tua applicazione di eseguire una funzione: descrivi gli strumenti disponibili con nomi, descrizioni e schemi dei parametri, il modello risponde con una chiamata strutturata come get_order_status(order_id="A-1042"), il tuo codice la esegue e il risultato torna al modello. Un agente è lo stesso meccanismo in un ciclo, in cui il modello continua a scegliere strumenti e a leggere i risultati finché decide che il compito è concluso.

Il modello non esegue mai nulla da solo. Produce testo che per caso è una richiesta ben formata. Tienilo a mente e molte scelte di progettazione sugli agenti diventano più chiare, soprattutto quelle di sicurezza.

Che aspetto ha la definizione di uno strumento?

Tra OpenAI, Anthropic e Google i formati delle richieste differiscono leggermente, ma ogni definizione di strumento ha le stesse tre parti: un nome, una descrizione in linguaggio naturale e un JSON Schema per i parametri.

Una definizione debole:

{
  "name": "search",
  "description": "Cerca roba.",
  "parameters": {
    "type": "object",
    "properties": { "q": { "type": "string" } }
  }
}

Una migliore:

{
  "name": "search_help_center",
  "description": "Ricerca full-text negli articoli pubblici del centro assistenza dell'app Ledgerly. Usalo quando l'utente chiede come funziona una funzione o come risolvere un problema. Non cerca nei dati dell'account dell'utente; per quelli usa get_account_summary. Restituisce fino a 5 articoli con titolo, URL e un breve estratto.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Una breve frase di ricerca in inglese, ad es. 'export invoices to CSV'. Riformula la domanda dell'utente in parole chiave invece di passarla così com'è."
      }
    },
    "required": ["query"]
  }
}

La descrizione è un prompt. Il modello la legge per decidere quando usare lo strumento, cosa passare e cosa aspettarsi in cambio. La documentazione sull'uso degli strumenti di Anthropic sottolinea che le descrizioni dettagliate sono il fattore più importante per le prestazioni degli strumenti, e coincide con quello che si vede nella pratica.

Come si scrivono descrizioni che il modello usa correttamente?

Rispondi alle domande che si farebbe uno sviluppatore nuovo prima di chiamare un'API sconosciuta:

  • Cosa fa e cosa non fa? "Non cerca nei dati dell'account dell'utente" previene un'intera classe di chiamate sbagliate.
  • Quando va usato al posto di uno strumento simile? Gli strumenti sovrapposti sono la causa principale delle scelte sbagliate. Se due strumenti potrebbero gestire una richiesta, di' quale ha la precedenza.
  • Cosa significano i parametri, con esempi? I formati (date ISO, centesimi o dollari, ID con o senza prefisso) e un valore d'esempio per tutto ciò che è ambiguo.
  • Cosa restituisce? Compreso cosa significa un risultato vuoto.
  • Ha effetti collaterali? "Invia subito l'email; non si può annullare" cambia il comportamento di un modello attento, e dovrebbe cambiare il modo in cui la tua app lo controlla.

Dai agli strumenti nomi che si leggano bene uno accanto all'altro: search_help_center, get_account_summary, create_support_ticket. Evita nomi generici come search o run, che invitano all'uso improprio.

Restituisci anche errori utili. Se una chiamata fallisce, un risultato come "error": "order_id deve avere il formato A-1234; ricevuto 1234" permette al modello di correggere da solo la chiamata al passo successivo. Un semplice 500 no.

Come funziona il ciclo di un agente?

Il ciclo di base, che la maggior parte dei framework per agenti implementa con varianti:

  1. Invia al modello la conversazione, il system prompt e le definizioni degli strumenti.
  2. Se il modello risponde solo con testo, il turno è finito.
  3. Se risponde con una o più chiamate a strumenti, il tuo codice le convalida e le esegue.
  4. Aggiungi i risultati alla conversazione come risultati degli strumenti.
  5. Torna al passo 1.

Questo schema, che alterna ragionamento, azioni e osservazioni, è descritto nel paper ReAct (Yao et al., 2022) ed è la spina dorsale della maggior parte degli agenti costruiti da allora. Le API moderne lo supportano in modo nativo, comprese più chiamate a strumenti in un solo turno.

Il ciclo è semplice. Il lavoro vero sta nel farlo comportare bene.

Come deve decidere un agente quando fermarsi?

Due tipi di condizioni di arresto, e servono entrambi.

A livello di compito, nel prompt. Di' all'agente cosa significa "finito":

Hai finito quando la domanda dell'utente ha una risposta o hai stabilito
che non si può rispondere con gli strumenti disponibili.
Se dopo due ricerche non hai trovato articoli rilevanti, smetti di
cercare e di' all'utente cosa hai provato.
Fai una domanda di chiarimento invece di tirare a indovinare quando la
richiesta potrebbe riferirsi a più di un account o di una fattura.

Senza indicazioni di questo tipo, gli agenti tendono o a fermarsi troppo presto (rispondendo con la propria conoscenza senza cercare) o a non fermarsi (ripetendo la ricerca con piccole variazioni, sperando in un risultato migliore).

Limiti rigidi, nel codice. Un numero massimo di iterazioni, un budget di token o di costo e un timeout a tempo reale. Quando si raggiunge un limite, chiudi con grazia: restituisci quanto trovato finora e di' che il compito non è stato completato. Non affidarti mai al solo modello per fermare un ciclo che spende denaro.

Quali sono gli errori più comuni degli agenti?

Scelta dello strumento sbagliato. Di solito causata da strumenti sovrapposti o descrizioni vaghe. Correggi prima le descrizioni; se non basta, riduci il numero di strumenti disponibili per quel compito.

Argomenti allucinati. Il modello inventa un ID ordine perché l'utente ha detto "il mio ultimo ordine". Istruiscilo a cercare gli ID con uno strumento o a chiederli all'utente, e convalida gli argomenti nel codice prima di eseguire.

Cicli infiniti. L'agente ripete una chiamata che fallisce con minime variazioni. Individua nel tuo ciclo le chiamate ripetute identiche o quasi identiche e interrompile, e rendi gli errori degli strumenti abbastanza informativi da poterli correggere.

Successo prematuro. L'agente riferisce "Fatto, ho aggiornato il record" quando la chiamata di aggiornamento è in realtà fallita. Rendi espliciti nei risultati degli strumenti il successo o il fallimento e, per i compiti importanti, verifica l'esito con una chiamata di lettura separata.

Contesto gonfio. I risultati degli strumenti possono essere enormi (una pagina web intera, una query da 2.000 righe). I cicli lunghi riempiono il contesto di output ormai superato e il modello perde di vista l'obiettivo iniziale. Riduci o riassumi i risultati prima di restituirli e restituisci solo i campi che servono al modello.

Troppi strumenti. L'accuratezza tende a calare man mano che aggiungi strumenti, soprattutto se simili. Dai a ogni compito l'insieme utile più piccolo, oppure carica gli strumenti in modo dinamico in base alla richiesta.

E la sicurezza?

Ogni strumento è una capacità che una prompt injection può prendere in prestito. Se il tuo agente legge pagine web o email e ha anche uno strumento che invia messaggi, un attaccante che scrive il testo giusto in una pagina può riuscire a fargli inviare messaggi.

Regole pratiche:

  • Autorizza nel codice, non nel prompt. Lo strumento dovrebbe girare con i permessi dell'utente finale, così un modello tratto in inganno non può raggiungere dati che l'utente non potrebbe vedere.
  • Conferma le azioni con conseguenze. Pagamenti, cancellazioni, messaggi in uscita, cambi di permessi: mostra all'utente esattamente cosa succederà e richiedi l'approvazione.
  • Convalida gli argomenti. Validazione dello schema più regole di business (limiti di importo, destinatari consentiti) prima dell'esecuzione.
  • Separa gli strumenti di lettura da quelli di scrittura. Un passaggio di ricerca che ha solo strumenti di lettura non può danneggiare nulla, per quanto si confonda.

Ti serve davvero un agente?

Spesso no. Se i passaggi sono noti in anticipo (recupera, poi riassumi, poi formatta), una pipeline fissa di singole chiamate al modello costa meno, è più veloce e più facile da testare e da correggere. Gli agenti giustificano la loro complessità quando il percorso dipende davvero dai risultati intermedi: il modello deve cercare qualcosa per sapere cosa cercare dopo.

Una progressione ragionevole: parti da un singolo prompt; aggiungi il retrieval se servono fatti (cos'è la RAG); aggiungi una singola chiamata a uno strumento per una singola azione; solo dopo costruisci un ciclo.

Dove si colloca MCP?

Il Model Context Protocol, introdotto da Anthropic alla fine del 2024 e adottato poi da altri fornitori e strumenti, standardizza il modo in cui le applicazioni espongono strumenti e dati ai modelli. Risolve l'impiantistica: una definizione di server utilizzabile da molti client. Non cambia nessuno dei consigli precedenti. Uno strumento descritto male è confuso anche via MCP, e collegare molti server di terze parti aggiunge sia capacità sia superficie d'attacco.

Per il lato output delle chiamate agli strumenti (schemi, modalità strict, validazione), vedi come ottenere JSON affidabile dagli LLM. L'argomento strumenti e agenti trasforma queste scelte di progettazione in domande di pratica.

Domande frequenti

Che cos'è il tool calling negli LLM?

Il tool calling, detto anche function calling, permette a un modello di rispondere con una richiesta strutturata di eseguire una funzione che hai definito, come cercare in un database o inviare un'email. Il tuo codice esegue la funzione e restituisce il risultato al modello, che poi prosegue.

Il modello esegue lo strumento da solo?

No. Il modello produce solo il nome dello strumento e gli argomenti. La tua applicazione decide se eseguirlo, lo esegue e rimanda indietro il risultato, ed è per questo che i controlli dei permessi appartengono al tuo codice.

Qual è la differenza tra tool calling e agente AI?

Il tool calling è una singola capacità: il modello chiede di eseguire una funzione. Un agente è un ciclo in cui il modello decide ripetutamente quale strumento chiamare dopo, osserva i risultati e continua finché il compito è finito o si raggiunge un limite.

Quanti strumenti si possono dare a un agente?

Non c'è un limite fisso, ma l'accuratezza tende a calare quando gli elenchi di strumenti crescono e gli strumenti si sovrappongono. Tieni l'insieme piccolo e distinto per ogni compito, oppure carica gli strumenti rilevanti in modo dinamico.

  • #tool calling
  • #function calling
  • #agenti AI
  • #ciclo dell'agente
  • #MCP

Ora mettiti alla prova

TokIQ trasforma il prompt engineering in brevi quiz, con una spiegazione per ogni risposta.

Presto suApp StoreDisponibile suGoogle Play

Scrivi prompt migliori, poche domande al giorno.

Brevi quiz su vere decisioni di prompting, con una spiegazione per ogni risposta. Gratis per iniziare su iPhone e Android.

Presto suApp StoreDisponibile suGoogle Play