> For the complete documentation index, see [llms.txt](https://manuale.opencontent.it/manuali/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manuale.opencontent.it/manuali/oc-assistant/architettura-tecnica.md).
# L'Architettura tecnica
L'interazione parte dall'interfaccia di OpenCity AI Assistant, attraverso cui il funzionario dialoga con la piattaforma. La richiesta viene ricevuta dall'orchestratore, che gestisce l'intera logica operativa e decide quali componenti coinvolgere per produrre la risposta.
I componenti principali sono:
* **l'orchestratore**, l'agentic framework che coordina l'intera esecuzione: riceve la richiesta, stabilisce la strategia di risposta e attiva gli strumenti necessari;
* **il modello di linguaggio (LLM)**, che elabora il testo e genera le risposte; viene coordinato dall'orchestratore e può essere sostituito senza modificare il resto del sistema;
* **la base di conoscenza locale**, consultata in modalità Agentic RAG per recuperare informazioni pertinenti da normative, documenti dell'ente e fonti precaricate;
* **le funzionalità esterne**, richiamate tramite il protocollo aperto MCP (ad esempio, la ricerca aggiornata di normative da fonti esterne all'ente);
* **le funzionalità interne**, disponibili come integrazioni native (ad esempio, l'analisi di dati, la creazione di report e la gestione delle attività).
Il modello di linguaggio consulta la base di conoscenza e richiama le funzionalità esterne e interne in modo autonomo, a seconda di ciò che serve per rispondere alla richiesta specifica.
Lo stack tecnologico è interamente open source: i componenti principali includono LiteLLM per la gestione dei modelli, SurrealDB come base dati, Windmill per l'orchestrazione dei flussi e spaCy per l'elaborazione del linguaggio.
## Dal RAG all'Agentic RAG
Il modo in cui l'assistente cerca le informazioni rappresenta un cambio di approccio rispetto ai sistemi tradizionali basati su AI.
Nel RAG classico (Retrieval-Augmented Generation), è il messaggio dell'utente a fare da interrogazione diretta per la base di conoscenza: il sistema cerca i documenti più simili alla domanda posta e li usa come contesto per generare la risposta. È un approccio efficace ma rigido, che funziona bene quando la domanda è semplice e diretta.
Con l'Agentic RAG, è l'agente a decidere cosa cercare e come farlo, a partire dal messaggio del funzionario. L'agente può formulare interrogazioni multiple, concatenarle, rivalutare i risultati e cambiare strategia durante l'elaborazione, tutto in modo autonomo. Questo consente di gestire richieste complesse, ambigue o che richiedono di incrociare informazioni da fonti diverse.
Il risultato è una qualità di risposta significativamente più alta per i casi d'uso reali della PA, a fronte di un leggero aumento dei tempi di elaborazione rispetto al RAG classico.
## Agnosticismo rispetto ai modelli di linguaggio (LLM)
OpenCity AI Assistant **è agnostico rispetto alla soluzione LLM** (*Large Language Model*) adottata, garantendo:
* **intercambiabilità dei modelli**: attualmente il sistema utilizza Gemini, integrato tramite Google Agentic Platform, 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.
Questa scelta non è solo tecnica: risponde al principio di evitare il vendor lock-in, particolarmente rilevante per la PA, che deve poter governare le proprie scelte tecnologiche nel tempo senza dipendere da un singolo fornitore.
---
# 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:
```
GET https://manuale.opencontent.it/manuali/oc-assistant/architettura-tecnica.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.