Un prompt che funziona oggi può smettere di funzionare tra due settimane senza che nessuno abbia toccato una riga di codice. Basta che il fornitore sostituisca il modello dietro un alias, che una policy di rifiuto cambi o che un nuovo modello risponda con una virgola in più. Secondo il sondaggio Stack Overflow 2025, l’84% degli sviluppatori usa o prevede di usare strumenti di IA e il 51% dei professionisti li usa ogni giorno.
In pratica il prompt engineering resta quasi sempre un lavoro manuale: si prova, si legge la risposta, si decide a occhio. Ottobre 2026 mostra quanto sia fragile quell’approccio. OpenAI ha distribuito GPT‑6.1 Terra il 26 ottobre, Google ha aperto Gemini 4 Argon a tutti il 13 ottobre, Anthropic ha annunciato Claude Haiku 5.5 il 7 ottobre. In quattro settimane tre fornitori hanno spostato il riferimento su cui si costruiscono i prodotti IA.
Perché il prompt engineering richiede test automatici
Un prompt è codice scritto in linguaggio naturale, eseguito da un interprete che cambia nel tempo. Questa frase riassume il problema. Il codice tradizionale ha un compilatore, un type checker e una suite di test che segnalano la rottura entro minuti. Un prompt non ha niente di tutto questo: se il modello inizia a rispondere “Certo! Ecco il JSON richiesto:” prima della graffa aperta, il parser a valle va in errore alle tre di notte e nessun log spiega perché.
Il ritmo dei rilasci rende il rischio concreto. Nelle sole ultime settimane OpenAI ha ritirato GPT‑5.5 da ChatGPT, ChatGPT Work e Codex il 14 ottobre 2026, lasciando però invariato l’accesso via API. Nello stesso giorno ha comunicato che alcuni modelli della serie GPT‑4 saranno rimossi dall’API il 14 gennaio 2027. Un team che dipende da un identificativo di modello deve quindi sapere con quale anticipo scoprirà una scadenza e come verificherà che il sostituto si comporti in modo equivalente.
I test automatici rispondono a tre domande che il controllo manuale non regge:
- Il nuovo prompt è migliore del precedente su tutti i casi, non solo su quello che ho appena provato?
- Il modello B, più economico, produce risultati accettabili sullo stesso insieme di input del modello A?
- Dopo l’aggiornamento di un modello, qualcosa che prima passava ora fallisce?
Senza una suite le tre risposte sono impressioni. Con una suite diventano tre righe di un report.
Il progetto promptlab: struttura e componenti
Il progetto si chiama promptlab e fa cinque cose:
- Carica un prompt versionato da un file YAML.
- Lo applica a una lista di casi, ciascuno con un input e un elenco di asserzioni.
- Esegue le chiamate su uno o più modelli in parallelo, con cache su disco e nuovi tentativi in caso di errore di rete.
- Valuta le risposte con controlli deterministici, tra cui la validazione di uno schema Pydantic.
- Stampa un report con tasso di successo, latenza al 95° percentile, costo ogni cento chiamate e test instabili, e termina con codice di uscita 1 se qualcosa è peggiorato.
Il caso d’uso è ordinario: un’azienda italiana riceve ticket scritti dai clienti e vuole un JSON con quattro campi – categoria (fatturazione, accesso, tecnico, altro), urgenza, flag dati personali e riepilogo di una frase. È un compito adatto a un modello piccolo e veloce, ma la suite permette di verificare se il modello scelto soddisfa i requisiti prima di metterlo in produzione.
Il progetto include anche un provider simulato, basato su regole. Serve a due scopi:
- Permettere di eseguire tutto il tutorial senza chiavi e senza spendere un centesimo.
- Rendere i test dell’harness deterministici, cosa che nessun modello reale garantisce.
I provider reali per OpenAI, Anthropic, Gemini e per qualunque endpoint compatibile con le Chat Completions, Ollama compreso, usano la stessa interfaccia. Passare dal simulatore a un modello vero significa cambiare un nome nella riga di comando.
Struttura della repository
promptlab/
├── models.yaml # modelli, parametri e prezzi per milione di token
├── prompts/
│ ├── triage_v1.yaml # prompt ingenuo
│ └── triage_v2.yaml # prompt rinforzato
├── cases/triage.yaml # 7 casi con asserzioni
├── promptlab/
│ ├── config.py # lettura YAML con ${VARIABILI}
│ ├── providers.py # OpenAI, Anthropic, Gemini, compat, demo
│ ├── checks.py # asserzioni e schema Pydantic
│ ├── runner.py # parallelismo, cache, retry
│ ├── report.py # tabella, costi, baseline, regressioni
│ └── _main_.py # riga di comando
├── tests/
│ ├── test_checks.py # test unitari dell'harness
│ └── test_suite.py # la suite dei prompt dentro pytest
├── .github/workflows/prompts.yml
└── requirements.txt
La scelta di non usare un framework esterno è deliberata. Esistono strumenti maturi, e più avanti nell’articolo si vede quando conviene adottarli. Ma scrivere l’harness a mano una volta sola chiarisce che cosa si sta misurando: un prompt, un modello, un insieme di input, un insieme di criteri. Tutto il resto, dai dashboard ai giudici basati su LLM, è un’estensione di queste quattro cose.
Prerequisiti e versioni consigliate
Il progetto richiede un ambiente Python moderno e poche dipendenze. Le versioni indicate sono quelle con cui il codice dell’articolo è stato eseguito e verificato il 28 ottobre 2026. Per i pacchetti dei fornitori conviene installare l’ultima release disponibile, perché gli SDK cambiano con le versioni delle API.
| Componente | Versione | Note |
|---|---|---|
| Python | 3.12 o successivo | Verificato con Python 3.12.3 su Linux |
| pydantic | 2.x | Schema di validazione della risposta (testato con 2.14) |
| pyyaml | 6.x | Lettura di prompt, casi e modelli (testato con 6.0) |
| pytest | 9.x | Test dell’harness e suite dei prompt in CI (testato con 9.2) |
| openai | ultima release | Provider openai (Responses API) e compat (Chat Completions) |
| anthropic | ultima release | Provider Claude, serve solo con chiave Anthropic |
| google-genai | ultima release | Provider Gemini, serve solo con chiave Gemini |
| Ollama | ultima release | Facoltativo, per provare un modello locale senza chiavi |
Per eseguire il tutorial con il solo provider simulato bastano Python 3.12, pip e i pacchetti elencati nel requirements.txt. Dopo aver clonato la repository, è sufficiente:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m promptlab --prompt prompts/triage_v1.yaml --cases cases/triage.yaml
Il comando avvierà i test su tutti i provider configurati in models.yaml. Il risultato sarà un report tabellare con metriche di accuratezza, latenza e costo, e un codice di uscita che può essere catturato da una pipeline CI.
Quando conviene adottare framework esterni
Se il team ha già una infrastruttura di test complessa, è possibile integrare promptlab con framework come LangChain o Semantic Kernel. In tal caso, l’harness rimane il cuore della logica di asserzione, mentre il framework fornisce:
- Gestione avanzata delle chain di LLM.
- Cache distribuita e tracciamento dei costi a livello di organizzazione.
- Integrazione con monitoraggio e alerting già in uso.
La decisione dipende dal livello di maturità del processo di sviluppo AI in azienda. Per startup o progetti pilota, la soluzione leggera presentata è sufficiente.
Conclusioni
Automatizzare i test dei prompt è diventato imprescindibile in un panorama dove i modelli cambiano settimanalmente e le policy di fornitura possono variare all’improvviso. Con pochi centinaia di righe di Python e un file YAML è possibile creare una suite di test che verifica stabilità, accuratezza, costi e conformità. Il progetto promptlab dimostra come, partendo da un caso d’uso concreto – la classificazione di ticket di assistenza in italiano – si può ottenere una pipeline CI completa, riutilizzabile e indipendente da chiavi API.
Adottare questa disciplina permette ai team di:
- Ridurre i rischi di rottura inattesa dei prompt.
- Ottimizzare la scelta del modello in base a costi e prestazioni.
- Garantire la conformità nella gestione di dati sensibili.
- Documentare in modo trasparente le evoluzioni del prompt nel tempo.
In un’era in cui l’IA è parte integrante dei prodotti software, trattare i prompt come codice vero e proprio, con test, versionamento e CI, è l’unico modo per mantenere la qualità e la fiducia degli utenti.