Dal prompt al prodotto: perché un chatbot non basta
Quando si inizia a lavorare con gli LLM, la tentazione è fortissima:
un prompt di sistema, una chat history, un wrapper attorno alle API di OpenAI… e voilà.
Funziona. Impressiona. Sembra già “il prodotto”.
Per un po’.
Il problema emerge quando smetti di giocare e inizi a costruire qualcosa che deve reggere nel mondo reale.
Nel mio caso: un assistente per docenti, che lavora con contenuti certificati, materiali editoriali, lezioni, verifiche ed esami di Stato.
A quel punto un semplice chatbot non basta più.
Serve analisi.
Serve una strategia.
Serve, soprattutto, un’architettura.
1. Il principio della “Fluidità Controllata”
Il cuore del problema è questo: gli LLM sono probabilistici.
Sono creativi, brillanti, sorprendenti. Ma non sono deterministici.
Un software professionale, invece, DEVE esserlo.
La prima regola architetturale che ci siamo dati è stata necessaria: mai esporre l’output grezzo di un LLM all’infrastruttura critica.
Niente payload inventati.
Niente “più o meno va bene”.
Niente fiducia cieca.
L’immagine mentale che usiamo è questa:
l’LLM è un liquido potentissimo. Ma scorre dentro tubature rigide.
- L’Agente ragiona, sintetizza, genera contenuti.
- Il Workflow gestisce stato, validazione, routing, persistenza.
- Ogni output passa attraverso schemi rigorosi (shout-out to zod).
Se l’output non rispetta lo schema, il sistema non va avanti.
Non “ci prova lo stesso”. Si ferma.
2. Separazione dei poteri: cervello vs processo
Uno degli errori più comuni nei sistemi LLM-driven è il God Agent.
Un unico prompt che:
- saluta l’utente
- capisce cosa vuole
- cerca nel db
- decide cosa fare dopo
- formatta il JSON
- gestisce la memoria
- e magari ti cucina anche una carbonara 🍝
Risultato?
Prompt ingestibili, contesto confuso, bug impossibili da debuggare.
Noi abbiamo separato tutto in tre ruoli molto netti.
🧠 Gli Agenti (Il Cervello)
Sono specialisti verticali.
Abbiamo il Lesson Creator Agent che sa solo strutturare lezioni, il Content Retrieval Agent che sa solo cercare.
La cosa fondamentale? Sono stateless.
Ricevono un input, ragionano, producono un output e muoiono.
Non sanno nulla di database, di runId, o di cosa ha detto l'utente tre turni fa, se non glielo passiamo esplicitamente. Questo mantiene il contesto pulito e riduce le allucinazioni.
🔀 I Workflow (Il Sistema Nervoso)
I workflow (basati su framework) orchestrano il tutto.
Sanno cosa succede prima e cosa dopo.
Decidono quando sospendere l'esecuzione, quando validare un dato, quando chiamare un agente.
Gestiscono il ciclo di vita del processo, non il pensiero creativo.
💪 I Tool
Funzioni atomiche. Non prendono decisioni, sono strumenti. Eseguono e restituiscono dati grezzi.
La lezione è controintuitiva:
più rendi gli agenti "stupidi" riguardo al processo e allo stato, più il sistema diventa intelligente e affidabile
3. Il Concierge: routing semantico invece di prompt giganti
Le richieste dei docenti sono imprevedibili.
- “Ciao, come posso rendere la mia classe più inclusiva?”
- “Mi serve un video sui vulcani per domani”
- “Crea una lezione di un’ora su Manzoni per la quarta superiore”
Sono richieste completamente diverse.
Gestire tutto questo con un solo agente significa sprecare token e confondere il modello. Abbiamo introdotto il Concierge: un Router Semantico. È un agente piccolissimo, veloce ed economico (spesso un modello "mini"), invisibile all'utente. Il suo unico compito è classificare l'intento in categorie rigide (es. GENERAL_REQUEST, CONTENT_SEARCH, LESSON_CREATE) e instradare la richiesta verso il workflow specifico.
1 [ MESSAGGIO UTENTE ]
2 │
3 ▼
4 [ IL CONCIERGE ]
5 (Classificatore Intent)
6 / │ \
7 / │ \
8 ┌─────────┐ ┌──────────┐ ┌─────────┐
9 │ GENERAL │ │ CONTENT │ │ LESSON │
10 │ CHAT WF │ │ SEARCH WF│ │ ARCH. WF│
11 └─────────┘ └──────────┘ └─────────┘
12 (Low Cost) (RAG only) (Reasoning)
13
14 Questo ha un impatto tecnico enorme:
- Isolamento: Il workflow di chat non deve caricare i tool pesanti di creazione lezione.
- Costi: Usiamo modelli costosi (o-series) solo quando serve ragionamento complesso, e modelli rapidi per la chat.
- Testabilità: Possiamo testare il modulo di "Creazione Lezione" in isolamento, senza preoccuparci che l'agente inizi a chiacchierare del meteo.
Il Concierge non è “intelligente” nel senso umano.
È un receptionist perfetto.
4. Un solo punto di accesso ai contenuti: Il Bibliotecario
Un’altra trappola classica: duplicare la logica di retrieval ovunque.
La chat cerca contenuti.
La creazione lezioni cerca contenuti.
Risultato: due implementazioni diverse, risultati incoerenti.
Noi abbiamo fatto l’opposto: un solo workflow per il retrieval, riusabile ovunque.
Il Bibliotecario:
- decide se interrogare Algolia o Istella
- gestisce query ambigue con ricerche parallele
- normalizza entità (“Dante” → “Dante Alighieri”)
- restituisce risultati sempre strutturati
1Richiesta: "Mi serve materiale su Dante"
2 │
3 [ IL BIBLIOTECARIO ]
4 / │ \
5 / │ \
6 / │ (Router) \
7(Video) (Encicl.) (Both)
8 \ │ /
9 \ │ /
10 \ │ /
11 [ MERGE ]
12 (Normalizzati e Citabili)
13
14 Chi lo usa non sa come recupera i dati.
Sa solo che arrivano contenuti certificati, coerenti e tracciabili.
5. Human-in-the-loop come cittadino di prima classe
Qui è dove l'architettura web tradizionale fallisce. Creare una lezione non è una chiamata API da 300 millisecondi.
È una conversazione.
L'agente propone una bozza, il docente la legge, ci pensa, e magari risponde dopo 20 minuti (o il giorno dopo). Un normale server HTTP andrebbe in timeout dopo 30 secondi.
1
2[ AGENTE ] -> "Ecco la bozza. Va bene?"
3 │
4 (SOSPENSIONE)
5 │
6 [ SALVA STATO SU DB ]
7 (runId: xyz-123)
8 │
9 ... 20 Minuti ...
10 │
11[ UTENTE ] -> "Sì, ma aggiungi un video"
12 │
13 (RIPRESA)
14 │
15 [ CARICA STATO DA DB ]
16 │
17[ AGENTE ] -> "Modifico la bozza..."
18
19Abbiamo dovuto progettare i workflow per il "Tempo Umano". Il sistema supporta nativamente la sospensione:
- L'agente arriva a un punto decisionale.
- Il workflow serializza l'intero stato della memoria su database (con un runId) e "uccide" il processo attivo.
- Quando l'utente risponde, il sistema recupera lo stato dalla memoria persistente, lo "idrata" e riprende l'esecuzione esattamente dal punto in cui si era interrotta.
Non c'è magia. C'è solo il rispetto per i tempi dell'utente e un'architettura che non tiene la connessione aperta inutilmente.
Costruire sistemi, non demo
Un LLM da solo è impressionante.
Un sistema agentico ben progettato è affidabile.
Ma la differenza tra un giocattolo e un prodotto non è il modello che usi (quello è una commodity). Passare dal prompt al prodotto significa smettere di sperare che l'AI "capisca tutto" e iniziare a progettare i binari su cui farla correre.