> 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.

<figure><img src="/files/ciTcO0cfBEfmgFtD74wl" alt=""><figcaption></figcaption></figure>

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 codice è rilasciato con licenza OpenSource su [GitLab](https://gitlab.com/opencity-labs/opencity-ai/ai-orchestrator)
* **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**: l'architettura è predisposta per integrare qualsiasi modello 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.&#x20;