Hai visto i pezzi separati: obiettivi ben definiti, strumenti esterni, limiti chiari, memoria che tiene il filo, valutazione che misura la qualità. Adesso è il momento di metterli insieme in qualcosa che funziona e che qualcun altro può usare davvero. Non un esperimento da laboratorio, un agente che consegni a un collega e che fa il suo lavoro quando tu non ci sei.

Questo è il capstone del percorso builder: costruisci qualcosa di completo, lo metti alla prova con qualcuno che non sei tu, e scopri dove servono guardrail che non avevi previsto.

L’idea: da componenti a sistema

Un agente pronto per altri è come una macchina che deve funzionare anche quando non sei tu a guidarla. Ogni pezzo che hai visto nei capitoli precedenti resta al suo posto, ma adesso devono lavorare insieme senza che tu debba aggiustare il tiro a ogni giro. L’obiettivo è esplicito, gli strumenti sono collegati, i limiti sono attivi, la memoria tiene traccia di quello che conta, e la valutazione ti dice se il risultato è buono prima che arrivi all’utente.

L’immagine che aiuta: un collega nuovo che conosce la procedura, ha gli strumenti giusti sulla scrivania, sa quando fermarsi a chiedere, e prima di consegnarti il lavoro lo controlla con una lista. Non è autonomo perché sa tutto, è autonomo perché ha guardrail chiari e strumenti pronti.

In pratica: un agente che riordina le note di una chiamata

Scegli un compito che fai davvero, che altre persone del tuo team fanno, e dove il risultato si può verificare. Prendiamo un esempio concreto: riordinare le note di una chiamata con un cliente in un documento strutturato pronto da condividere. Il risultato deve avere sempre gli stessi blocchi (partecipanti, punti discussi, decisioni prese, prossimi passi), e non deve inventare cose che non erano nelle note.

Parti dall’obiettivo. Il prompt di sistema dell’agente dice:

Sei un assistente che riordina le note di una chiamata in un documento strutturato.
Ricevi note grezze e produci un documento con queste sezioni, in quest'ordine:
- Partecipanti
- Data e durata
- Punti discussi
- Decisioni prese
- Prossimi passi con responsabile e scadenza

Usa solo le informazioni presenti nelle note. Se una sezione non ha contenuto, scrivilo esplicitamente.
Non aggiungere interpretazioni tue.

Gli strumenti. In questo caso ne servono due: uno per leggere il file con le note grezze, uno per scrivere il documento finale. Se lavori con un framework come LangChain o un’API diretta, colleghi le funzioni read_file(path) e write_file(path, content). L’agente può chiamarle quando servono.

I limiti, i guardrail veri: l’agente può leggere solo file nella cartella input/ e scrivere solo in output/; il documento finale non supera le 1000 parole; se nelle note non trova almeno due partecipanti e una data, si ferma e chiede conferma; se una sezione resta vuota, scrive “Nessuna informazione disponibile”, non inventa. Non sono paranoia: sono il risultato di aver visto cosa va storto la prima volta che qualcuno usa l’agente con dati veri, e li implementi come controlli nel codice, non come semplici raccomandazioni nel prompt.

La memoria. L’agente tiene traccia di quali file ha già processato in questa sessione e non li riprocessa. Se l’utente gli chiede di rifare un documento, recupera il contenuto precedente e lo usa come punto di partenza per la correzione. Questo serve quando qualcuno dice “aggiungi che Mario è il responsabile del punto 3”: l’agente deve sapere cosa c’era prima.

La valutazione. Prima di scrivere il file finale, l’agente passa il contenuto a una funzione di controllo che verifica:

• Tutte le sezioni sono presenti.
• Ogni “prossimo passo” ha un responsabile e una scadenza o dice esplicitamente che mancano.
• Non ci sono frasi tipo “probabilmente” o “sembra che”, che sono segnali di invenzione.

Se un controllo fallisce, l’agente riscrive quella sezione.

Metti insieme tutto in un flusso:

1. L’utente dà il path del file con le note grezze.
2. L’agente verifica che il path sia in input/.
3. Legge il file.
4. Controlla che ci siano almeno partecipanti e data, altrimenti si ferma.
5. Produce il documento strutturato.
6. Lo passa ai controlli di validazione.
7. Se i controlli passano, scrive il file in output/ e conferma all’utente.

Questo è un agente completo. Adesso arriva la parte che conta.

La prova vera: un utente diverso da te

Scegli qualcuno che userebbe davvero questo agente, spiegagli come funziona in due frasi, dagli un paio di file di esempio, e guardalo lavorare. Non intervenire. Osserva dove si inceppa, dove l’agente fa una cosa che tu non avevi previsto, dove l’utente si aspetta un comportamento diverso.

Nella prova con l’agente che riordina le note, sono emersi tre casi che non avevi previsto: un utente ha dato note in due lingue mescolate e l’agente ha prodotto sezioni in lingue diverse (serviva chiedere quale lingua usare); un altro ha dato note di una chiamata di tre ore e l’agente ha tagliato pezzi importanti per stare sotto il limite di parole (il limite era troppo rigido, meglio avvisare invece di tagliare); un terzo ha caricato un file con dati sensibili di un cliente e l’agente li ha riscritti senza avviso (serviva un controllo che chiedesse conferma davanti a parole come “riservato”).

Questi sono guardrail che non avresti mai scritto da solo, perché tu sai come si usa l’agente e non provi a metterlo in difficoltà. Un utente vero ci prova senza volerlo, e ti mostra esattamente dove servono protezioni in più.

Una cosa da fare

Costruisci il tuo agente completo. Scegli un compito che fai almeno una volta a settimana, che ha un risultato verificabile, e che qualcun altro nel tuo team potrebbe usare. Segui questa scaletta:

1. Scrivi l’obiettivo in forma di prompt di sistema, con il risultato atteso esplicito.
2. Collega almeno uno strumento esterno (leggi o scrivi un file, chiama un’API, cerca in un database).
3. Aggiungi tre guardrail: due su cosa l’agente non può fare, uno su quando deve fermarsi e chiedere.
4. Implementa la memoria per tenere traccia di quello che conta nella sessione.
5. Scrivi una funzione di validazione che controlla il risultato finale.
6. Testa con i tuoi dati finché non funziona.
7. Mettilo in mano a qualcuno che non sei tu, con una spiegazione brevissima, e osserva.

Annota dove l’utente si blocca, dove l’agente fa qualcosa che non ti aspettavi, e dove il risultato non è quello giusto. Quelli sono i posti dove serve un guardrail in più o un limite più chiaro.

Prompt pronti

Il prompt di sistema completo, con i guardrail emersi dalla prova con l’utente aggiunti a quello visto sopra:

Sei un assistente che riordina le note di una chiamata in un documento strutturato.
Ricevi note grezze e produci un documento con queste sezioni, in quest'ordine:
- Partecipanti
- Data e durata
- Punti discussi
- Decisioni prese
- Prossimi passi con responsabile e scadenza

Usa solo le informazioni presenti nelle note. Se una sezione non ha contenuto, scrivi "Nessuna informazione disponibile".
Non aggiungere interpretazioni tue.
Se le note contengono più lingue, chiedi quale usare per il documento finale.
Se il file contiene "riservato" o "confidenziale" nell'intestazione, chiedi conferma prima di procedere.

La funzione di validazione (pseudocodice che adatti al tuo linguaggio):

funzione valida_documento(contenuto):
  sezioni_richieste = ["Partecipanti", "Data e durata", "Punti discussi", "Decisioni prese", "Prossimi passi"]
  per ogni sezione in sezioni_richieste:
    se sezione non in contenuto:
      ritorna errore "Manca la sezione [sezione]"

  se "probabilmente" in contenuto o "sembra che" in contenuto:
    ritorna errore "Il documento contiene frasi speculative"

  righe_prossimi_passi = estrai_sezione(contenuto, "Prossimi passi")
  per ogni riga in righe_prossimi_passi:
    se riga non contiene responsabile e non dice "Nessuna informazione":
      ritorna errore "Prossimo passo senza responsabile: [riga]"

  ritorna ok

Il kit del capstone

Ogni pezzo della scaletta ha un materiale del corso da cui partire, così il capstone si costruisce assemblando e adattando invece che partendo dal foglio bianco.

Lo scheletro è l’agente minimo del primo capitolo: ha già il ciclo, tre strumenti sui file e i limiti nel codice, e l’esempio della lezione (riordinare le note di una chiamata) si ottiene sostituendo il suo prompt di sistema con quello qui sopra. I dati di prova sono la trascrizione di riunione dei materiali del corso, che contiene esattamente le insidie discusse in questa lezione, con l’output atteso per verificare: il prezzo deciso dopo una trattativa, il vincolo temporale implicito, la questione rimandata che non è una decisione. La validazione del punto 5 diventa un banco di prova con i tuoi casi, che ti accorgi subito se una modifica rompe qualcosa. E la spiegazione brevissima per l’utente del punto 7 è un handoff compilato: obiettivo, cosa fa, cosa non fa, fatto vuol dire.

Il capstone è completo quando: l’agente passa il banco di prova con i tuoi casi più la trascrizione di esempio; una persona diversa da te ha completato un giro intero senza il tuo aiuto; le domande che ti ha fatto durante il giro sono annotate e hanno prodotto almeno un guardrail o una riga di documentazione in più; e la checklist della sezione seguente è tutta spuntata.

Cosa controllare prima di considerarlo pronto

Prima di consegnare l’agente a qualcun altro, verifica che: l’obiettivo sia esplicito nel prompt di sistema, non sottinteso; gli strumenti siano collegati e testati con dati veri, non solo di esempio; i guardrail coprano i casi limite visti nella prova con l’utente; la memoria tenga traccia di quello che serve senza accumulare tutto; la validazione controlli il risultato prima che esca dall’agente; i messaggi di errore dicano cosa fare, non solo cosa è andato storto; la documentazione per l’utente stia in due paragrafi, cosa fa l’agente e cosa aspettarsi.

Se un punto manca, l’agente funziona per te ma non per altri.

Dove andare adesso

Questo chiude il percorso builder, e con esso i tre percorsi del corso: principiante, pro e builder. Hai costruito un agente che usa tutti i pezzi insieme, l’hai messo in mano a qualcuno che non sei tu, e sai cosa controllare prima di chiamarlo pronto. È lo stesso metodo dei primi capitoli, applicato a qualcosa che adesso regge da solo: un obiettivo chiaro, verificato da chi lo usa, non da chi l’ha costruito.