> 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/cosa-fa/ciclo-di-test-e-ottimizzazione-di-ai-assistant.md).

# Ciclo di test e ottimizzazione di AI Assistant

OpenCity AI Assistant è stato sottoposto a un ciclo di test basato su richieste realistiche, pensate per chi lavora ogni giorno negli Enti. L'obiettivo è verificare che l'assistente sia uno strumento affidabile per il funzionario nello svolgimento delle sue attività quotidiane, dalle più semplici alle più complesse.

Non è una semplice verifica tecnica: i test misurano quanto l'Assistente risponde alle esigenze concrete del lavoro amministrativo.

### Obiettivi dei test

I test rispondono a tre esigenze:

* **uso reale**: le richieste riproducono il lavoro quotidiano di segretari comunali, RTD, dirigenti e funzionari, dalla bozza di una determina a un post per i social;
* **affidabilità**: in un contesto pubblico, un riferimento normativo sbagliato ha conseguenze concrete; per questo, abbiamo verificato con particolare attenzione le norme citate nelle risposte;
* **solidità**: le richieste variano per ambito, forma e livello di dettaglio e l'Assistente deve restare preciso sia sui quesiti brevi sia sulle richieste articolate.

### Tipologie di test

Per coprire le diverse situazioni d'uso, abbiamo previsto quattro tipologie di test complementari:

* **analisi dei casi d'uso**: abbiamo costruito le richieste a partire dalle attività più frequenti dei profili a cui l'Assistente si rivolge;
* **validazione della qualità delle risposte**: ogni risposta è stata valutata in modo sistematico su cinque criteri;
* **scenari trasversali**: richieste che toccano ambiti diversi, dalla redazione di atti al bilancio, dal personale alla comunicazione;
* **casi limite e fuori perimetro**: richieste ambigue, incomplete o estranee al contesto istituzionale, per verificare che l'Assistente non inventi informazioni e rifiuti le richieste scorrette.

#### Ambiti coperti

Le richieste hanno riguardato:

* redazione di atti: determine, ordinanze, bandi, convenzioni, contestazioni e verbali;
* contratti pubblici, personale e bilancio;
* quesiti normativi brevi;
* comunicazione ai cittadini: avvisi, FAQ (domande frequenti), post social e newsletter;
* richieste fuori perimetro o volutamente ambigue.

#### Esempi di richieste

Ecco alcune delle richieste usate nei test:

* "Scrivimi la bozza di una determina per l'affidamento diretto della manutenzione del verde a Rossi S.r.l. (25.000 € + IVA, ex art. 50 D.Lgs. 36/2023)";
* "Quando posso procedere con affidamento diretto senza gara per un servizio?";
* "Il RUP di una gara è cugino di primo grado dell'amministratore dell'impresa partecipante. C'è conflitto d'interessi? Cosa deve fare il Segretario?";
* "Come RTD di un Comune di 10.000 abitanti, crea una matrice con le 5 priorità del Piano Triennale AgID (scadenze e KPI)";
* "Redigi una contestazione di addebito disciplinare per un dipendente assente ingiustificato, con termine di 20 giorni per le difese";
* "La riscossione in competenza è scesa dall'80% al 60% in 3 anni. Scrivi un breve report per la Giunta con raccomandazioni";
* "Crea 10 FAQ chiare per il sito web sul nuovo sistema di raccolta differenziata";
* "Cosa ha dichiarato oggi l'arcivescovo di Milano?".

### Come abbiamo condotto i test

Abbiamo sottoposto all'Assistente **un'ampia batteria di richieste**. Ogni risposta è stata valutata con un punteggio da 1 a 3 per ciascun criterio e accompagnata da osservazioni qualitative.

#### Criteri di valutazione

* **Correttezza**: la risposta è corretta anche nei riferimenti giuridici e non contiene contenuti inventati;
* **Aderenza alla domanda**: risponde esattamente a ciò che è stato chiesto, senza divagazioni;
* **Completezza**: copre gli aspetti principali senza lacune;
* **Leggibilità**: grassetti, elenchi e tabelle sono usati con criterio e rendono il testo facile da scorrere;
* **Concisione**: evita ridondanze e testo superfluo, mantenendo ciò che serve.

#### Scala di valutazione

* **3 (ottimale)**: la risposta soddisfa pienamente il criterio e non richiede interventi;
* **2 (migliorabile)**: la risposta è corretta e utile, ma può essere perfezionata, per esempio nella concisione o nella formattazione;
* **1 (non soddisfacente)**: la risposta non rispetta il criterio e richiede un intervento prioritario.

### Risultati

| Criterio              | Punteggio medio |
| --------------------- | --------------- |
| Correttezza           | 2,7             |
| Aderenza alla domanda | 3               |
| Completezza           | 2,9             |
| Leggibilità           | 2,8             |
| Concisione            | 2,6             |
| **Media**             | **2,8**         |

La correttezza è stata valutata con un criterio severo, che verifica anche ogni riferimento normativo citato.

#### Punti di forza

* **Bozze pronte da completare**: determine, ordinanze, dinieghi, lettere, checklist e convenzioni hanno la struttura corretta e segnaposto chiari dove servono i dati dell'ufficio;
* **documenti dell'Ente**: l'Assistente usa come modello gli atti caricati, applica le istruzioni operative e ricava dati anche da tabelle e immagini;
* **aderenza alla richiesta**: risponde a ciò che è stato chiesto e rifiuta le richieste scorrette.

### Alcuni problemi tipici dei sistemi AI

I modelli linguistici generano il testo più plausibile, non necessariamente quello verificato. Per questo, alcuni limiti emersi nei test sono comuni a tutti i sistemi di intelligenza artificiale generativa. Conoscerli aiuta l'utente a usare l'Assistente in modo consapevole.

#### Riferimenti normativi errati ma convincenti

Quando cita a memoria invece di verificare, l'Assistente può usare riferimenti superati, come il vecchio Codice dei contratti pubblici, categorie contrattuali abolite o reati abrogati. In alcuni casi indica soglie o termini errati e, raramente, articoli inesistenti. Il testo resta convincente, quindi l'errore è difficile da  notare: è il rischio principale per chi non conosce a fondo la materia.

#### Contenuti inventati quando mancano i dati

È il fenomeno noto come **allucinazione**. Su newsletter, FAQ, guide e circolari l'Assistente tende a inventare eventi, regole o dichiarazioni invece di chiedere le informazioni mancanti o chiedere chiarimenti all'utente.

#### Dettagli interni visibili nella risposta

Alcune risposte si aprono con il resoconto della ricerca svolta, per esempio "Non ho trovato istruzioni…". In pochi casi compaiono nomi di strumenti interni o messaggi di sistema.

#### Qualità del testo non sempre costante

In una parte dei test sono comparsi refusi, parole senza senso, frasi in inglese e un uso eccessivo di emoji, poco adatto ai testi istituzionali.

{% hint style="warning" %}
Verifica sempre norme, soglie e termini prima di adottare un atto. L'Assistente prepara e suggerisce, ma la decisione finale resta tua: è il principio del [human in the loop](https://claude.ai/ai/cosa-fa/cose-opencity-ai-assistant) su cui si basa tutta la piattaforma.
{% endhint %}

### Ottimizzazione continua

Le evidenze emerse guidano i prossimi interventi:

* rendere obbligatoria la verifica delle norme, delle soglie e dei termini prima di citarli, segnalando quando la verifica non è avvenuta;
* fare in modo che, se mancano dati, l'Assistente chieda le informazioni o usi segnaposto, senza inventare;
* nascondere all'utente i passaggi interni e rendere uniformi tono e qualità del testo.

Ripeteremo periodicamente i test sullo stesso set di richieste, per misurare i miglioramenti e mantenere alta la qualità nel tempo.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.opencityitalia.it/ai/cosa-fa/ciclo-di-test-e-ottimizzazione-di-ai-assistant.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
