> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/ai/architettura-e-funzionalita-del-chatbot/architettura-e-sicurezza-dei-dati/architettura-e-framework.md). # Architettura e framework ## Architettura software Il cuore tecnologico di OpenCity Chatbot AI si basa su un’architettura di tipo RAG (*Retrieval-Augmented Generation*). A differenza dei sistemi basati su sola intelligenza artificiale generica, questo approccio fa in modo che ogni risposta sia il più possibile ancorata esclusivamente a dati certi e verificati. Quando un utente pone una domanda, il flusso di elaborazione segue tre fasi principali: 1. *Retrieval*: la richiesta viene gestita dal componente open source OpenCity AI, che analizza il contenuto della domanda e interroga il motore di ricerca interno per individuare le informazioni specifiche presenti sul sito web dell'Ente; 2. Arricchimento del contesto: il sistema "arricchisce" la domanda dell'utente unendola ai frammenti di testo ufficiali recuperati dal sito. In questa fase, il chatbot ha già la risposta corretta sotto forma di dati grezzi; 3. *Generation*: il pacchetto informativo (domanda + dati ufficiali) viene inviato a un modello linguistico avanzato (LLM) tramite API sicure. In questa fase finale, l'LLM non attinge alla propria conoscenza generica, ma si limita a elaborare in forma di dialogo le informazioni ricevute, restituendo al cittadino una risposta chiara, cortese e precisa. Questa architettura garantisce la massima trasparenza grazie alla base open source e la massima affidabilità, poiché separa la fase di "conoscenza" (gestita dai dati comunali) dalla fase di "esposizione" (gestita dall'IA). ## Opensource e neutralità tecnologica OpenCity AI Chatbot è configurato come un modulo completamente autonomo, progettato per essere introdotto nell'ecosistema digitale dell'Ente senza generare vincoli o dipendenze tecnologiche. A differenza di altre soluzioni sul mercato, il sistema garantisce la massima libertà di manovra grazie a due pilastri: * **Nessun prerequisito di piattaforma**: il chatbot è pronto all'uso come **soluzione *****stand-alone***, capace di operare indipendentemente dai software già in dote all'Amministrazione; * **Nessun obbligo di migrazione**: l’Ente non è obbligato a migrare il proprio sito web o a modificare l’attuale infrastruttura digitale per poter beneficiare dell’assistente virtuale. Il sistema si integra sul portale esistente, permettendo all'Ente di evolvere i propri servizi ai cittadini senza dover affrontare i costi e le complessità di un cambio di piattaforma o di un trasloco di contenuti. Questa impostazione garantisce una piena interoperabilità e permette all'Ente di potenziare l'interazione con l'utenza in tempi rapidi, mantenendo intatto l'investimento tecnologico già effettuato sul proprio sito istituzionale. ### Erogazione in SaaS Il servizio viene fornito interamente in modalità SaaS (*Software as a Service*). Questa scelta architettonica è pensata per azzerare l’impatto sull'infrastruttura dell'Ente: essendo una soluzione *cloud* nativa, l'Ente non deve installare alcun software né configurare o gestire server dedicati. ### Agnosticismo rispetto ai modelli di linguaggio (LLM) OpenCity AI **è agnostico rispetto alla soluzione LLM** (*Large Language Model*) adottata, garantendo: * **intercambiabilità dei modelli**: attualmente il sistema utilizza Google Agentic Platform (ex Google Vertex AI), ma l'architettura è predisposta per integrare altri modelli leader di mercato a seconda delle necessità o dell'evoluzione tecnologica; * **sperimentazione**: il nostro team sta attivamente sperimentando l'uso di modelli locali Open Source. ### Ecosistema di plugin e repository L'estensibilità del sistema è garantita da un’architettura modulare che conta attualmente su 9 plugin interamente Open Source, progettati per potenziare le capacità di interazione e integrazione del chatbot. L'attuale configurazione prevede: * **6 plugin sviluppati internamente**: moduli progettati ad hoc dai nostri team per rispondere alle specifiche esigenze verticali della Pubblica Amministrazione italiana; * **3 plugin preesistenti**: componenti selezionati dalla comunità Open Source globale, integrati e ottimizzati per garantire la massima stabilità e interoperabilità. Tutti i moduli, corredati dalla relativa documentazione tecnica, sono descritti nella sezione [Gestione dei Plugin](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/installazione-chatbot/gestione-dei-plugin). ## Framework Il sistema si basa sul framework Open Source [Cheshire Cat AI v.1](https://cheshirecat.ai/) che, tramite il nostro contributo sotto forma di plug-in anche essi Open Source, permette di gestire tutto il flusso delle chat. Le funzionalità del prodotto ci permettono di: * avere sempre a disposizione le [informazioni](/ai/architettura-e-funzionalita-del-chatbot/chatbot-per-la-pa/funzionalita-del-chatbot.md#sincronizzazione-dei-contenuti-e-aggiornamento-dati) del sito web (aggiornate alla mezzanotte del giorno corrente); * mantenere la [privacy](/ai/architettura-e-funzionalita-del-chatbot/architettura-e-sicurezza-dei-dati/privacy-e-sicurezza-dei-dati.md) degli utenti tramite specifiche funzionalità di anonimizzazione; * mostrare le fonti da cui sono state prese le informazioni; * rifiutare richieste non pertinenti. ## Integrazioni e interoperabilità: analisi e adozione del Model Context Protocol (MCP) La nostra piattaforma è in costante evoluzione per allinearsi in modo fluido e sicuro all'ecosistema digitale della Pubblica Amministrazione. Per garantire la massima longevità e interoperabilità dei nostri sistemi, stiamo attivamente esplorando l'adozione del **Model Context Protocol (MCP)**, il nuovo standard per la comunicazione tra le intelligenze artificiali e i servizi dati. L'adozione di questo standard ha il potenziale per superare le tradizionali e rigide integrazioni API point-to-point, puntando a trasformare il nostro chatbot in un ecosistema sempre più *plug-and-play*. In prospettiva, ciò andrebbe a limitare il rischio di *vendor lock-in*, facendo sì che i futuri aggiornamenti ai servizi dell'Ente possano richiedere interventi minimi sul codice del chatbot, ottimizzando tempi e costi di manutenzione. La nostra analisi implementativa si sta sviluppando su due direttrici principali, al fine di studiare un flusso bidirezionale per i servizi della PA: ### Il chatbot verso un modello di agente universale (client MCP) L'obiettivo è quello di elevare il nostro assistente AI da strumento puramente conversazionale a sistema capace di interagire in modo proattivo con i servizi digitali dell'Ente. Le aree di indagine attuali includono: * **Integrazione sicura con SPID/CIE (privacy-first):** Lo scenario applicativo a cui puntiamo prevede la possibilità di far autenticare l'utente tramite i sistemi di identità digitale standard. In questa architettura, il server MCP agirebbe da ponte sicuro per la gestione della sessione SPID, facendo in modo che il "cervello" dell'IA (l'LLM) non debba mai entrare in possesso dei token diretti, a garanzia e tutela della privacy. * **Automazione assistita (agent loop):** La sperimentazione sull'MCP mira ad abilitare, in futuro, l'esecuzione di operazioni complesse in un'unica interazione semantica. A tendere, una volta autenticato, l'agente potrebbe essere in grado di visualizzare le pratiche di un cittadino, identificare documenti mancanti e prepararne l'aggiornamento sui sistemi dell'Ente, chiedendo all'utente unicamente le conferme finali necessarie. * **Connessione a servizi di terze parti:** Qualora l'Ente utilizzasse già software di altri fornitori compatibili con lo standard MCP, il nostro obiettivo è fare in modo che il chatbot possa interfacciarsi a tali servizi, ponendosi progressivamente come interfaccia unificata. ### Verso un'apertura all'ecosistema PA (server MCP) L'interoperabilità è un principio fondamentale delle linee guida AgID. Per questo motivo, stiamo studiando l'approccio tecnico per esporre progressivamente i nostri servizi proprietari tramite un nostro server MCP dedicato. Una volta a regime, questa architettura permetterà potenzialmente ad altri agenti AI in uso all'Ente di interrogare la nostra piattaforma in modo standardizzato, valorizzando il patrimonio informativo a tutti i livelli istituzionali. ### Sicurezza, governance e trasparenza Trattando dati sensibili, il controllo sulle azioni dell'IA resta il perno della nostra progettazione: * **Autorizzazioni granulari (RBAC):** L'architettura MCP sta venendo ingegnerizzata per permettere una configurazione flessibile dei permessi. L'intento è fornire all'Ente la capacità di definire a livello di server quali endpoint siano accessibili e con quali privilegi (es. limitare alcuni flussi alla sola consultazione e abilitare la scrittura solo per specifiche pratiche). * **Tracciabilità e auditing strutturato:** Sebbene ogni interazione del sistema sia già tracciata dalle nostre infrastrutture, stiamo valutando un'evoluzione per rendere in futuro la consultazione dei log ancora più accessibile per i responsabili dell'Ente, garantendo massima trasparenza amministrativa sulle richieste e sulle operazioni gestite dall'IA. * **Affidabilità e certezza del dato:** La prospettiva di integrazione real-time con i database dell'Ente (in sinergia con i nostri attuali sistemi RAG) ha lo scopo di fornire al chatbot un contesto sempre più basato su dati certificati e aggiornati, con l'obiettivo continuo di mitigare il rischio di allucinazioni. * **Trasparenza sull'interazione con l'AI:** In conformità a quanto stabilito dall'art. 50, comma 1, del Regolamento (UE) 2024/1689 (EU AI Act), la schermata di chat integra un avviso visivo permanente e ben visibile prima dell'invio del primo messaggio ("Le risposte sono generate con l'aiuto dell'intelligenza artificiale e potrebbero contenere inesattezze, verifica sempre le informazioni rilevanti"). In questo modo, l'utente è sempre consapevole dell'origine delle risposte che riceve. ### Roadmap e approccio allo sviluppo Trattandosi di un'evoluzione architetturale profonda e strettamente legata all'evoluzione degli standard globali dell'IA, l'introduzione delle funzionalità basate su Model Context Protocol avverrà in modo **progressivo e strettamente modulare**. Le fasi di test e sviluppo procederanno in parallelo con il rilascio dei nostri nuovi moduli software. Questo approccio flessibile e cauto ci permette di assicurare che ogni potenziale integrazione MCP venga rigorosamente validata prima dell'eventuale rilascio in produzione, tutelando la stabilità, la sicurezza e la continuità di servizio per le Pubbliche Amministrazioni. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.opencityitalia.it/ai/architettura-e-funzionalita-del-chatbot/architettura-e-sicurezza-dei-dati/architettura-e-framework.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.