Tool calling: progettare strumenti che l'agente usa bene
Quando un agente si comporta male, l'istinto è riscrivere il prompt. Per nostra esperienza il prompt è la causa forse un terzo delle volte; nel resto gli strumenti sono stati progettati per un programma e non per chi deve dedurre da nomi e descrizioni cosa fa una funzione.
Gli strumenti sono l'intera capacità dell'agente di incidere sul mondo, e le loro definizioni fanno letteralmente parte del contesto del modello. Progettarli bene costa meno ed è molto più duraturo del tuning dei prompt, perché un buon strumento vincola il comportamento invece di chiederlo.
Sette regole che evitano quasi tutte le chiamate sbagliate#
- Uno strumento, un compito. `search_orders` e `refund_order` battono un `manage_order` con modalità.
- Tipi, non prosa. Enum, intervalli e formati fanno ciò che una descrizione non farà mai.
- Nomi che dicono cosa succede. `send_email_to_customer` è inequivocabile; `notify` no.
- Errori come istruzioni: cosa non andava e cosa fare adesso, in una frase.
- I risultati vuoti sono risultati. Un non-trovato esplicito batte un'eccezione.
- Chiavi di idempotenza su tutto ciò che ha effetti, perché un ritentativo non duplichi.
- Ritorni piccoli. Tagliate ai campi necessari; 40 KB di JSON comprano confusione.
Prima e dopo#
| Design debole | Perché si rompe | Meglio |
|---|---|---|
| `query(sql)` | Potere illimitato, non verificabile | `get_orders_by_customer(customer_id, limit)` |
| `date: string` | Il modello inventa formati | `date: string, formato AAAA-MM-GG` |
| `HTTP 500` | Non implica azione, ritentato all'infinito | `Servizio ordini non disponibile. Di' al cliente di riprovare.` |
| Restituisce l'intero record | Riempie il contesto, diluisce l'attenzione | Restituisce sei campi nominati |
| `update_status(id, status)` | Qualsiasi stato, qualsiasi record | `cancel_order(id)` con controllo dei permessi |
Le descrizioni sono prompt#
Il campo descrizione non è documentazione per i colleghi: è testo che il modello legge mentre decide. Dite quando usare lo strumento e quando no, nominate l'unica precondizione che conta e date un esempio di argomento. Tre frasi battono tre paragrafi.
Se due strumenti potrebbero servire la stessa richiesta, l'agente a volte sbaglierà. Uniteli o rendete esplicito il confine in entrambe le descrizioni.
Validate sempre prima di eseguire#
Non passate mai output del modello a una chiamata di sistema senza controllo. Validate gli argomenti contro lo schema, risolvete gli identificatori su record che quell'utente può vedere, e rifiutate ciò che non corrisponde invece di forzarlo. Un rifiuto con messaggio chiaro è un buon esito.
Domande frequenti
Quanti strumenti sono troppi?
Oltre una decina in un ciclo, l'accuratezza di selezione cala e le descrizioni saturano il contesto.
Gli strumenti devono restituire risposte API grezze?
No. Restituite una forma piccola e stabile con i campi davvero necessari.
Come evito che inventi argomenti?
Vincolandoli: enum invece di testo libero, formati espliciti e identificatori che devono risolversi. Poi validate e rifiutate con chiarezza.
tool callingfunction calling agentidesign degli strumentijson schema strumentierrori strumenti llm
