Hai costruito un agente che funziona. Gli hai dato un obiettivo, ha compiuto i primi passi, e ora ti chiedi: di cos’altro ha bisogno? La tentazione è dargli accesso a tutto quello che potrebbe servire. Un collegamento al calendario, la rubrica dei contatti, la posta, il CRM, il sistema di fatturazione. Poi scopri che ha mandato una mail a un cliente sbagliato o che ha sovrascritto un appuntamento importante, e capisci che il problema non era cosa dargli, ma cosa non dargli.

Questo capitolo parte dal primo: hai un agente che riceve istruzioni e risponde. Adesso vediamo come equipaggiarlo senza aprire buchi.

L’idea: strumenti come porte, non come stanze

Un tool è una capacità che dai all’agente. Leggere una mail, scrivere su un foglio di calcolo, cercare informazioni in un database, chiamare un’API esterna. Senza tool, l’agente può solo ragionare sul testo che gli passi. Con i tool giusti, può compiere azioni nel mondo reale.

L’immagine che aiuta è quella di una porta stretta invece di una stanza aperta. Non gli dai accesso a tutto Google Calendar con il permesso di fare quello che vuole. Gli dai un tool specifico che legge gli impegni di domani, e un altro che crea un evento solo se riceve data, ora e titolo precisi. Ogni tool è una porta con una maniglia e una serratura, non una stanza con dentro tutto.

Questo modo di ragionare rovescia l’approccio comune. Invece di partire da tutto quello che potrebbe servire, parti da quello che serve davvero per il compito che gli hai dato. Invece di pensare “ha bisogno di accedere ai dati”, chiedi “quale dato preciso, in quale momento, e con quale limite”.

In pratica: un caso vero

Devi costruire un agente che prepara il resoconto settimanale per il tuo team. Legge le mail della settimana, tira fuori i punti salienti, li mette in ordine e scrive una bozza. Senza tool non va da nessuna parte, perché le mail stanno da un’altra parte. Con i tool sbagliati ti ritrovi con un agente che può leggere tutta la posta aziendale e scrivere a chiunque.

La soluzione pratica è dargli esattamente due tool:

1. Leggi mail del team. Accetta un intervallo di date e restituisce oggetto, mittente e corpo delle mail mandate alla lista del team. Non legge la posta personale di nessuno, non può aprire allegati, non vede le bozze.
2. Scrivi su documento condiviso. Accetta testo formattato e lo aggiunge a un documento già esistente, in fondo. Non può creare nuovi documenti, non può sovrascrivere quello che c’è già, non può condividerlo con altri.

Ogni tool ha un confine preciso, scritto nel codice o nella configurazione dello strumento che usi per costruire l’agente. Non è una raccomandazione nel prompt, è un limite tecnico: l’agente non può fare altro nemmeno se prova.

Il primo giro ti accorgi che manca qualcosa: l’agente non sa quali mail sono importanti e quali no. Invece di dargli un tool che legge tutto, aggiungi un terzo confine al primo tool: legge solo le mail con un’etichetta specifica o mandate da certi mittenti. Il confine si stringe, il risultato migliora.

Quando un tool in più peggiora le cose

Ogni strumento che aggiungi porta con sé due rischi. Il primo è tecnico: più tool hai, più combinazioni sbagliate l’agente può provare. Un agente con cinque tool prova strade che con tre non avrebbe mai imboccato, e alcune di quelle strade finiscono male.

Il secondo rischio è più sottile: ogni tool aggiunge superficie di attacco. Se l’agente può scrivere su un foglio di calcolo, qualcuno può cercare di fargli sovrascrivere i dati veri con dati fasulli. Se può mandare mail, qualcuno può cercare di fargli mandare spam. I confini che metti attorno agli strumenti sono anche i confini che proteggono il sistema.

La regola pratica è semplice: aggiungi un tool solo se senza non arrivi al risultato. Non “potrebbe servire”, non “prima o poi sarà utile”. Serve adesso, per questo compito, altrimenti aspetti.

Confini precisi, non genericamente prudenti

C’è una differenza enorme tra dire “stai attento con le mail” nel prompt e dare all’agente un tool che può solo leggere le mail degli ultimi sette giorni mandate a una lista precisa. Il primo è un consiglio, il secondo è un vincolo. L’agente segue bene le istruzioni, ma le istruzioni non bastano quando arriva un caso limite o quando qualcuno cerca di forzare la mano.

I confini vanno scritti dove contano, cioè nella definizione del tool. Alcuni esempi concreti:

• Lettura dati: quali tabelle, quali colonne, quale intervallo di date. Non “leggi il database”.
• Scrittura documenti: quale file, quale sezione, append o sovrascrittura. Non “scrivi dove serve”.
• Chiamate API: quali endpoint, quali parametri, quale rate limit. Non “usa l’API”.
• Accesso mail: quali cartelle, quali mittenti, quali etichette. Non “leggi la posta”.

Ogni volta che ti viene voglia di scrivere “con cautela” o “solo quando necessario” in un prompt, fermati e chiediti se quel vincolo può diventare un confine tecnico del tool.

Una cosa da fare

Prendi un agente che hai già costruito o che stai costruendo. Elenca i tool che ha o che pensavi di dargli. Per ognuno, scrivi su un foglio:

1. Cosa fa, in una riga.
2. Quali dati può leggere, e con quali limiti.
3. Quali azioni può compiere, e con quali limiti.
4. Cosa non può fare, anche se tecnicamente potrebbe.

Se un tool occupa mezza pagina perché fa troppe cose, spezzalo in due tool più stretti. Se un limite ti sembra impossibile da scrivere perché dipende dal contesto, quello è un segnale che il tool è troppo largo: restringilo finché il confine diventa scrivibile.

Datti venti minuti. Se arrivi alla fine e ti accorgi che un tool che pensavi necessario non ha un confine chiaro, toglilo. Meglio un agente che fa meno cose bene che uno che fa tutto male.

Prompt pronti

Quando definisci un tool per l’agente, usa questo schema:

Nome tool: [nome_breve]
Scopo: [cosa fa, in una riga]
Input richiesti: [parametri obbligatori]
Confini tecnici:
- Può accedere a: [lista precisa]
- Non può accedere a: [lista precisa]
- Limiti operativi: [rate limit, dimensioni, formati]
Output: [cosa restituisce]

Se usi un framework che accetta descrizioni in linguaggio naturale, trasforma questo schema in un testo ma mantieni la stessa precisione.

Fallo davvero

La differenza tra consiglio e vincolo si può toccare con mano nell’agente minimo del capitolo precedente, che è costruito esattamente su questo principio. Aprilo e guarda due punti. La funzione percorsoSicuro rifiuta qualunque percorso che esca dalla cartella di lavoro: il prompt dice all’agente di lavorare solo lì, ma se il modello un giorno chiedesse ../documenti-privati.txt, il codice glielo nega comunque, con un errore che torna al modello come risultato del tool. E il tool scrivi_file non sovrascrive: se il file esiste, l’operazione fallisce a prescindere da quanto il modello insista.

La verifica pratica: lancia node agente-minimo.mjs --prova due volte di fila. Al secondo giro il modello finto prova a riscrivere lo stesso file, il codice rifiuta, e nell’output vedi il confine che regge dove l’istruzione da sola non basterebbe. È il collaudo detto nella lezione sul primo agente, chiedere qualcosa appena fuori dal limite, applicato però al livello giusto: il tool, non il prompt.

Quando compili lo schema qui sopra per un tool tuo, la riga «non può accedere a» va poi tradotta in questo tipo di controllo nel codice o nella configurazione, ovunque il tuo strumento lo permetta. Ogni confine che vive solo nel prompt è un confine di cortesia.

Dove andare adesso

Nel prossimo capitolo, Collegare l’agente ai tuoi sistemi (MCP e dintorni), vediamo come questi stessi principi di confine si applicano quando colleghi l’agente a sistemi esterni tramite un protocollo standard invece che tool su misura.