Il problema delle istruzioni che crescono

Hai imparato a dare istruzioni chiare a un assistente, hai visto che con un po’ di contesto e qualche correzione ottieni risultati spendibili. A un certo punto ti accorgi che le istruzioni si allungano: devi ricordargli dove trovare i file, come preferisci il formato, quali fonti controllare prima di rispondere. Ricopiare tutto a ogni conversazione nuova diventa faticoso, e il rischio di dimenticare qualcosa cresce.

È il momento di costruire il tuo primo agente. Non un assistente generico a cui affidi un compito ogni volta, ma uno strumento configurato per un lavoro preciso, che parte con le istruzioni giuste già dentro.

Cos’è un agente costruito per davvero

Un agente è un programma che gira attorno a un modello linguistico, con tre cose scritte in modo chiaro fin dall’inizio: l’obiettivo, gli strumenti a disposizione, e i limiti entro cui deve restare. L’assistente che usi via chat può diventare agente quando lo configuri per uno scopo specifico e gli dai accesso a risorse precise.

L’analogia più utile è quella di un collega nuovo che arriva per dare una mano su un progetto. Se gli dici solo «aiutami con la ricerca», si guarda intorno spaesato. Se gli spieghi «devi raccogliere articoli recenti su questo argomento, controllare che siano del 2024 o dopo, e riassumere i punti chiave in un elenco», sa cosa fare. Aggiungi «usa solo fonti verificate e segnalami quando non sei sicuro», e hai definito anche i limiti. L’agente parte da lì.

Obiettivo: la cosa da ottenere

L’obiettivo è il risultato che ti aspetti, scritto in modo che tu e l’agente lo riconosciate quando arriva. Non «aiutami con la ricerca», che può voler dire tutto e niente, ma «dammi cinque articoli recenti con il riassunto di ciascuno in tre righe». Non «prepara la riunione», ma «una scaletta di cinque punti con i tempi per ciascuno e i materiali da portare».

Un buon obiettivo ha tre caratteristiche. È concreto: sai che forma ha il risultato finito. È verificabile: guardandolo capisci se è fatto bene o no. È piccolo abbastanza da starci in una sessione di lavoro: se l’obiettivo è troppo grande, lo spezzi in passi e fai un agente per ciascuno.

Esempio reale. Devi tenere traccia delle richieste che arrivano via mail da clienti diversi, e ogni tanto qualcosa ti sfugge. L’obiettivo dell’agente non è «gestire le mail», ma «leggere le nuove mail, estrarre cliente, oggetto e urgenza, e aggiornare una tabella che controllo ogni mattina». Il risultato è una cosa che puoi aprire e giudicare in dieci secondi.

Strumenti: cosa può davvero usare

Gli strumenti sono le risorse concrete a cui l’agente ha accesso. Non gli attributi magici («è creativo», «sa programmare»), ma le cose che può fare o leggere. Un agente che lavora sui tuoi documenti ha accesso a una cartella precisa. Uno che cerca in rete ha una funzione di ricerca. Uno che ti aggiorna una tabella ha il permesso di scrivere in quel file.

Quando configuri un agente, questa è la domanda da farti: «Di cosa ha bisogno per portare a casa l’obiettivo?». Se deve riassumere gli appunti di una riunione, gli serve accesso a quegli appunti. Se deve controllare il sito di un fornitore, gli serve una funzione che scarica quella pagina. Se deve segnalarti i messaggi urgenti, gli serve leggere la casella di posta.

Più sono precisi gli strumenti, più il risultato è affidabile. Un agente con accesso generico a «internet» ti riporta qualunque cosa. Uno con accesso a tre fonti verificate che gli hai indicato tu fa un lavoro che puoi usare.

Limiti: dove deve fermarsi

I limiti sono le cose che l’agente non deve fare, nemmeno se gli sembra una buona idea. Non sono punizioni, sono protezioni. Un limite chiaro fa la differenza fra un agente che ti semplifica la giornata e uno che combina pasticci che poi tocca a te sistemare.

Un esempio concreto. Stai costruendo un agente che risponde alle richieste di informazioni sulla tua attività. Il limite principale è: «Se non conosci la risposta, dillo e passa la domanda a me. Non inventare». Sembra ovvio, ma se non lo scrivi esplicitamente, il modello proverà a rispondere lo stesso, magari con qualcosa di plausibile e sbagliato.

Altro limite frequente: «Non cancellare niente, solo aggiungi». Vale per gli agenti che aggiornano tabelle o documenti. Oppure: «Non spendere più di tot tempo su una singola ricerca». Vale per quelli che interrogano API a pagamento o che potrebbero girare a vuoto.

I limiti si scrivono nella configurazione dell’agente, nel campo delle istruzioni di sistema, e vanno testati. Un buon banco di prova è chiedergli di fare qualcosa che sta appena fuori dal limite, per vedere se si ferma o ci prova lo stesso.

In pratica: il tuo primo agente

Partiamo da un compito vero e piccolo: tenere una lista aggiornata degli articoli interessanti che trovi durante la settimana, con un riassunto di due righe per ciascuno. È un lavoro che fai già, magari salvando i link in una nota disordinata, e che un agente può fare meglio di te.

Obiettivo: una tabella con data, titolo, link e riassunto in due righe, aggiornata ogni volta che gli passi un articolo.

Strumenti: accesso a un file condiviso (una tabella su Google Sheets o Notion, o un file Markdown), funzione per leggere l’articolo dal link, modello linguistico per fare il riassunto.

Limiti: non modifica gli articoli già in lista, solo aggiunge. Se un articolo è in paywall o non si riesce a leggere, lo segna e passa oltre invece di inventare il contenuto. Non decide da solo cosa è interessante: sei tu che gli passi i link.

La configurazione la scrivi nel prompt di sistema dell’agente (se stai usando un’API) o nelle istruzioni iniziali (se stai usando un tool con interfaccia). Lo scaffolding di ricerca che trovi su questo link ti mostra un esempio di struttura simile, già pronto.

Una cosa da fare

Scegli un compito piccolo e ripetitivo che fai almeno una volta a settimana. Deve avere un risultato verificabile: una lista aggiornata, un report di poche righe, una tabella con tre colonne. Scrivi su un foglio, in tre righe, obiettivo, strumenti e limiti.

Obiettivo: cosa deve consegnarti.

Strumenti: a cosa ha accesso (file, funzioni, cartelle).

Limiti: cosa non deve fare, anche se gli sembra utile.

Se non ti viene in mente niente di tuo, prendi l’esempio della lista articoli qui sopra e adattalo. Il punto non è partorire l’idea perfetta, è prendere confidenza con il fatto che un agente si costruisce attorno a queste tre cose, non attorno a un blocco di codice incomprensibile.

Prompt pronti

Questo è il template base per configurare un agente. Copialo, riempi le parentesi, e usalo come istruzioni di sistema.

Sei un agente costruito per [obiettivo preciso].

Hai accesso a:
- [strumento 1, es. file X nella cartella Y]
- [strumento 2, es. funzione di ricerca su fonti Z]
- [strumento 3, se serve]

I tuoi limiti:
- [limite 1, es. non modificare file esistenti, solo aggiungi]
- [limite 2, es. se non conosci la risposta, segnalalo e fermati]
- [limite 3, se serve]

Procedi passo per passo. A ogni passo, dimmi cosa stai facendo e perché.

Questo secondo prompt è per testare che l’agente rispetti i limiti:

[Dagli un compito appena fuori dal limite, es. "cancella la prima riga della tabella" se il limite dice di non cancellare niente]

Se l’agente prova a farlo lo stesso, il limite va riscritto in modo più netto. Se si ferma e ti dice che non può, funziona.

Fallo davvero

Obiettivo, strumenti e limiti smettono di essere concetti quando li vedi girare, e il corso ti dà un agente vero da guardare dentro: agente-minimo.mjs, un file solo, commentato per essere letto, senza niente da installare a parte Node. Il primo giro si fa senza chiave API e senza spendere nulla:

node agente-minimo.mjs --prova

Vedrai il ciclo completo stampato passo per passo: l’agente elenca i file della cartella di lavoro, legge quello che gli serve, scrive il risultato, e chiude con un resoconto. Quella sequenza, decisa dal modello a ogni passo invece che fissata in anticipo, è la differenza tra un agente e uno script.

Poi aprilo con un editor di testo qualsiasi e ritrova le tre cose di questa lezione: l’obiettivo arriva dalla riga di comando, gli strumenti sono tre funzioni con nome e descrizione (elenca_file, leggi_file, scrivi_file), e i limiti stanno in due posti, nel prompt di sistema e nel codice. Quando hai una chiave di OpenRouter, rilancialo senza --prova su un obiettivo tuo, per esempio riassumere un file di appunti vero nella cartella lavoro.

Dove andare adesso

Il prossimo capitolo, Dare gli strumenti giusti (tools) e i loro confini, entra nel dettaglio di come scegliere e limitare gli strumenti visti qui. Se invece vuoi partire da un esempio già montato e modificarlo per il tuo caso, guarda lo scaffolding research-agent, che raccoglie e riassume articoli da fonti che scegli tu.