Gaia: assistente virtuale AI per Spapperi

Progettazione, hardening e messa in produzione di un assistente conversazionale AI integrato nel sito istituzionale di un produttore di macchine agricole — oltre alla riprogettazione del sito stesso.

Il cliente

SPAPPERI NT S.r.l. — azienda italiana di Città di Castello (PG) specializzata nella produzione di macchine agricole (trapiantatrici, rimorchi, stendifilm, baulatrici, raccoglitrici, sarchiatrici, ecc.), con un catalogo ampio organizzato per linee di business (Orticole, Tabacco, Officinali, Arboree) e dati agronomici strutturati (tipi di trapianto, sesti di impianto, tipi di pianta).

Sito multilingua (IT, EN, FR, DE, ES, PT, ZH) basato su Next.js + Payload CMS, in produzione su VPS con stack Docker (PostgreSQL, Caddy, layer di cache).

Prima e dopo

Abbiamo riprogettato da zero il sito istituzionale e tutto il listino, modernizzando l'esperienza desktop e mobile: dalla homepage alla navigazione per linea di business, fino alle schede macchina con specifiche tecniche, configuratore e galleria.

Homepage

Prima

Dopo

Navigazione per linea di business

Il vecchio catalogo era una lista piatta. Ora i prodotti sono organizzati per linea di business (Orticole, Tabacco, Officinali/Aromatiche, Arboree, Usato) con filtri per macchinario, coltura, tipologia di terreno e tipo di pianta.

Prima

Dopo

Scheda macchina

Dalla pagina prodotto statica a una scheda tecnica completa: specifiche di trapianto, caratteristiche tecniche, configuratore di allestimenti/accessori, galleria e download catalogo.

Prima

Dopo

La sfida

Il cliente voleva un assistente virtuale capace di:

• rispondere su tutto il catalogo prodotti e i dati agronomici senza che l'utente debba navigare il sito;
• indirizzare in modo corretto a contatti, ricambi, candidature e servizi;
• funzionare in 7 lingue;
• essere conforme agli obblighi legali (trasparenza AI, GDPR);
• offrire una UX mobile all'altezza di una chat moderna.

Un primo rilascio aveva raccolto un feedback dettagliato dal cliente (9 punti, con screenshot delle conversazioni) che evidenziava problemi di tono, struttura delle risposte, link errati e mancanza di identità/disclosure dell'AI. In parallelo, l'infrastruttura presentava limiti di scalabilità (cache assente, rate limiting in-memory) e una lacuna di compliance (le informative non menzionavano il chatbot).

Come funziona Gaia

Gaia non è un chatbot a risposte preconfezionate: è un agente conversazionale collegato in tempo reale al CMS del sito. Quando un utente fa una domanda, il modello non "indovina" — usa il function calling per interrogare direttamente i contenuti reali di Spapperi.

• Accesso al CMS via function calling: il modello dispone di un set di tool (funzioni) che leggono in tempo reale dal Payload CMS — catalogo prodotti, serie e modelli, dati agronomici (tipi di trapianto, sesti di impianto, tipi di pianta), pagine di servizio, ricambi e contatti. L'AI decide quale tool chiamare e con quali parametri, riceve i dati strutturati e costruisce la risposta su quei dati.
• Sempre allineata ai contenuti veri: poiché le risposte vengono generate sui dati live del CMS, quando il cliente aggiorna un prodotto o un prezzo l'assistente risponde subito con l'informazione corretta — niente knowledge base da ri-addestrare, niente risposte obsolete. Un hook di invalidazione azzera la cache a ogni modifica dei contenuti.
• Recupero multi-modello e multilingua: un singolo tool può restituire più macchine in un'unica richiesta (es. "scheda tecnica di AS PT e AS AT") con i rispettivi cataloghi, in tutte e 7 le lingue supportate.
• Niente allucinazioni di link: gli URL provengono dal CMS, sempre relativi e validi — eliminati i percorsi che generavano 404 e i riferimenti a pagine non più esistenti.

Conformità: AI Act + GDPR

L'assistente è stato progettato per essere conforme agli obblighi normativi europei:

• EU AI Act — trasparenza: l'AI Act impone che gli utenti sappiano di interagire con un sistema di intelligenza artificiale. Gaia si presenta esplicitamente come assistente virtuale AI (nome, avatar e disclosure), con greeting localizzato in ogni lingua: nessuna ambiguità sul fatto di parlare con una macchina.
• GDPR: le informative legali sono state aggiornate per coprire il trattamento dei dati via chatbot — Privacy Policy, Cookie Policy e Termini di Servizio, nei punti corretti dei documenti e in tutte e 7 le lingue (OpenAI indicato tra i responsabili del trattamento e nei trasferimenti extra-UE). Vedi il dettaglio nella sezione Compliance GDPR più sotto.

La soluzione

1. Identità e qualità conversazionale

Dall'analisi del feedback cliente sono stati derivati interventi mirati sul system prompt e sui tool:

• Identità "Gaia" + disclosure AI: l'assistente si presenta esplicitamente come assistente virtuale AI (obbligo di trasparenza), con nome, avatar dedicato e greeting localizzato in tutte le lingue.
• "Linee di business prima": le risposte sui prodotti vengono inquadrate partendo dalle linee di attività, poi scendono nel dettaglio di serie e modelli.
• Gestione link rigorosa: niente link proattivi se non richiesti; URL sempre relativi e validi (eliminati percorsi che generavano 404); rimossi riferimenti a pagine non più esistenti.
• Ricambi: instradamento diretto alla piattaforma ricambi ufficiale invece della generica sezione servizi.
• Recupero multi-modello: il tool di dettaglio macchina accetta più modelli in un'unica richiesta, così domande come "scheda tecnica di AS PT e AS AT" restituiscono tutti i modelli con i rispettivi cataloghi.
• Niente leakage tecnico: eliminata la comparsa di marcatori interni ([slug:...]) nel testo mostrato all'utente.

2. Performance: caching su Redis

Ogni messaggio ricostruiva il contesto con ~11 query al CMS. È stato introdotto un servizio Redis nell'infrastruttura Docker e un caching a due livelli:

• System prompt cacheato per lingua;
• Risposte FAQ (primo turno) servite dalla cache, saltando del tutto il modello;
• Invalidazione automatica: hook sulle collection/globals sorgente del chatbot azzerano la cache a ogni modifica dei contenuti nel CMS;
• Fallback graceful: se Redis è irraggiungibile, l'app continua a funzionare senza cache (mai un errore in faccia all'utente).

3. Sicurezza: rate limiting distribuito

Il rate limiting in-memory (che si azzerava a ogni deploy e non reggeva più istanze) è stato migrato su Redis con script Lua atomico, condiviso tra processi e persistente, con fallback in-memory. Copre ~17 endpoint API (contatti, ricerca, login area riservata, candidature, GDPR, ecc.).

4. Compliance GDPR

Le informative legali non menzionavano il trattamento via chatbot. Sono state inserite, nei punti corretti dei documenti (non in coda) e in tutte e 7 le lingue:

• Privacy Policy: nuova sotto-sezione sui dati trattati dall'assistente, riga nelle tabelle "Finalità" e "Conservazione", OpenAI tra i responsabili e nei trasferimenti extra-UE;
• Cookie Policy: righe nella tabella delle tecnologie tecniche per il localStorage del widget;
• Termini di Servizio: clausola dedicata all'assistente AI (carattere informativo, non vincolante).

L'inserimento è avvenuto tramite uno script idempotente che individua sezioni e tabelle in modo robusto su tutte le lingue, con backup preventivo dei contenuti.

5. UX/UI mobile

Esperienza ridisegnata in stile chat moderna:

• pannello fullscreen su mobile;
• niente zoom indesiderato all'apertura della tastiera (input a 16px);
• layout stabile con tastiera aperta (altezza ancorata al viewport visibile);
• animazione di apertura/chiusura;
• avatar dedicato di Gaia (header + launcher).

6. Messa in produzione

Deploy controllato sul VPS: backup del database di produzione, sincronizzazione del codice (esclusi segreti e volumi runtime), allineamento dati e rebuild Docker con avvio del nuovo servizio Redis — senza perdita di dati e con verifiche end-to-end (container healthy, cache popolata, pagine legali aggiornate, chatbot operativo).

Risultati

• Identità e compliance: l'assistente si dichiara AI in tutte le lingue; colmata la lacuna GDPR su 3 documenti legali × 7 lingue (21 aggiornamenti, 0 anomalie).
• Performance: il costo per messaggio crolla sulle richieste ripetute grazie a due livelli di cache, con coerenza garantita dall'invalidazione automatica.
• Robustezza: rate limiting ora distribuito e persistente; cache e rate limiting degradano in modo sicuro se Redis non è disponibile.
• Qualità risposte: risolti i punti di feedback risolvibili lato prodotto (identità, struttura, link, ricambi, multi-modello, niente leakage tecnico).
• UX mobile: esperienza chat fluida, senza zoom e senza rotture di layout con la tastiera.
• Zero downtime percepibile e zero perdita dati in fase di rilascio.

Il valore per il business

Dietro l'aspetto tecnico, Gaia e il nuovo sito risolvono problemi concreti di un'azienda manifatturiera che vende prodotti complessi e lavora con clienti in tutto il mondo.

• Un commerciale che non stacca mai. Gaia risponde 24/7 su catalogo, dati agronomici, ricambi e servizi: il potenziale cliente trova subito la macchina giusta senza aspettare un'email o una telefonata. Le richieste semplici si chiudono da sole, quelle qualificate arrivano al team già mature.
• Meno carico sull'assistenza. Le domande ricorrenti (modelli, compatibilità colture, dove trovare i ricambi) vengono gestite dall'assistente, liberando tempo prezioso alle persone per le trattative che contano davvero.
• Mercati esteri davvero raggiungibili. Con 7 lingue native, un cliente francese, tedesco o cinese vive la stessa esperienza di uno italiano. Per un'azienda Made in Italy che esporta, è un canale commerciale in più, sempre attivo e a costo marginale quasi nullo.
• Posizionamento e immagine. Un sito moderno e un assistente AI proprietario comunicano innovazione tanto quanto i prodotti: il cliente percepisce un'azienda al passo coi tempi, non solo un buon costruttore di macchine.
• Catalogo sempre aggiornato, zero manutenzione doppia. Poiché Gaia legge il CMS in tempo reale, basta aggiornare il prodotto una volta: sito e assistente restano allineati. Niente listini paralleli da mantenere, niente informazioni datate che fanno perdere vendite.
• Conformità = tranquillità. Trasparenza AI (AI Act) e GDPR in regola fin dal primo giorno: nessun rischio legale o reputazionale, un asset solido anche in ottica di clienti enterprise e gare.

In sostanza: lo stesso investimento ha prodotto più richieste qualificate, meno tempo perso in attività ripetitive e una presenza internazionale credibile — con un'infrastruttura pronta a crescere senza rifare tutto da capo.

Stack tecnologico

Ambito	Tecnologie
Frontend	Next.js (App Router), React, framer-motion
CMS / Backend	Payload CMS, PostgreSQL
AI	OpenAI (function calling / tool use)
Caching & rate limiting	Redis (ioredis, script Lua)
Infrastruttura	Docker Compose, Caddy, layer di cache, VPS
i18n	7 lingue (IT, EN, FR, DE, ES, PT, ZH)

In sintesi

Da un primo prototipo con feedback aperto a un assistente AI identificabile, conforme, performante e robusto, integrato col catalogo reale del cliente e rilasciato in produzione in sicurezza. L'architettura introdotta (Redis, hook di invalidazione, fallback graceful, rate limiting distribuito) costituisce inoltre una base riutilizzabile per ulteriori funzionalità (token monouso, anti-abuso, caching di pagine pesanti, analytics).

Chatbot "Gaia" — RayoChat by Rayo Consulting.