Come scrivere prompt di sistema per agenti IA che non falliscono in produzione

Sommario

Aggiornato luglio 2026.

TL;DR: Un prompt di sistema in produzione ha cinque livelli: identità (chi è l’agente e cosa non può fare), contesto (cosa sa dell’ambiente), compito (come appare il successo passo dopo passo), formato di output (il livello più sottovalutato) e casi limite (cosa fare quando gli input sono difettosi). La maggior parte dei prompt fallisce perché salta i livelli 4 e 5. Scrivi il formato di output prima di tutto il resto — ti obbliga a essere preciso su cosa vuoi davvero.

[Prospettiva dell’operatore] Gestisco oltre 30 agenti IA in produzione per il mio brand di consulenza e Pickleland, un impianto di pickleball a Pflugerville, TX. Ho riscritto più prompt di sistema di quanti ne abbia scritti — di solito perché la prima versione sembrava funzionare bene nei test e poi si degradava silenziosamente in produzione. Questo è quello che ho imparato su come scrivere prompt che durano.

Il problema del prompt di sistema che nessuno ammette

La maggior parte dei prompt di sistema per gli agenti viene scritta in circa 20 minuti, testata su due o tre esempi e poi non viene mai più toccata. Il modello viene distribuito. Per un po’ funziona. Poi qualcosa cambia — gli input diventano più caoticii, il modello viene aggiornato, appare un nuovo caso limite — e l’agente inizia a produrre spazzatura. In silenzio. Su scala.

Il problema non è che il prompt originale fosse cattivo. È che la maggior parte dei prompt viene scritta per dimostrare il percorso felice. Sono progettati per l’input che avevi in mente quando hai costruito l’agente, non per la distribuzione completa degli input che l’agente vedrà effettivamente.

I cinque livelli di un prompt di sistema in produzione

Penso a ogni prompt di sistema che scrivo in cinque livelli. Non devono apparire in questo ordine — ma devono essere tutti presenti.

Livello 1: Identità

L’identità dice al modello chi è e quali sono i suoi vincoli operativi. Non un personaggio di gioco di ruolo — una definizione funzionale di cosa fa e non fa questo agente.

Un forte livello di identità risponde a tre domande:

• Di cosa è responsabile questo agente?
• Di cosa NON è esplicitamente responsabile (e dovrebbe escalare o rifiutare)?
• Quali standard mantiene?

Il perimetro esplicito di cosa NON è incluso è la parte che la maggior parte degli operatori salta. Senza di essa, il modello cercherà di essere utile al di fuori del suo ambito — ed è lì che le cose vanno storte.

Livello 2: Contesto

Il contesto è ciò che l’agente sa del suo ambiente che non è nel messaggio dell’utente. Include la data e l’ora correnti (da iniettare dinamicamente — non fidarti mai del senso interno del tempo del modello), lo stato rilevante dai sistemi esterni e le regole aziendali che non sono ovvie dalla descrizione del compito.

La maggior parte degli agenti che esamino è povera di contesto. Non assumere. Inietta.

Livello 3: Compito

Il livello del compito descrive cosa fa l’agente, passo dopo passo. Non “aiutare i clienti” — il vero flusso decisionale. Scrivilo come un diagramma di flusso, non come una direttiva. I diagrammi di flusso sono più robusti perché riducono la necessità del modello di inferire cosa vuoi nei casi ambigui.

Livello 4: Formato di output

Questo è il livello più sottovalutato, e quello più responsabile dei fallimenti silenziosi.

Se non specifichi il formato di output con precisione, il modello produrrà un output che sembra corretto a un lettore umano ma è sufficientemente incoerente da rompere l’analisi a valle. Scrivi il formato di output per primo. Per output strutturati, specifica lo schema esatto. Per output in prosa, specifica struttura, lunghezza e vincoli di tono.

Per gli agenti ad alto rischio, uso l’output strutturato di Claude con uno schema JSON definito.

Livello 5: Casi limite

Il livello dei casi limite risponde: cosa fa l’agente quando l’input è ambiguo, incompleto, nella lingua sbagliata, ostile o chiaramente errato? Per ogni caso limite, dai al modello un percorso di risposta esplicito.

Come mantengo i prompt di sistema nel tempo

Un prompt di sistema in produzione è un documento vivo:

1. Controllo puntuale settimanale. Esamino da cinque a dieci output casuali di ogni agente ad alto rischio rispetto all’output atteso.
2. Revisione dopo l’aggiornamento del modello. Ogni volta che la versione del modello sottostante cambia, eseguo l’agente contro il golden set completo del mio framework di valutazione.
3. Log dei casi limite. Tengo un log degli input che l’agente ha gestito male. Quando tre o più voci condividono un pattern, aggiungo una regola esplicita.
4. Versionamento del prompt. Ogni modifica significativa riceve un commento di versione.

Domande frequenti

Quanto dovrebbe essere lungo un prompt di sistema in produzione?

Abbastanza lungo da coprire tutti e cinque i livelli. Abbastanza corto da poterlo leggere in due minuti e individuare la deriva. Per la maggior parte dei miei agenti, sono 200-600 parole.

Quando dovrei dividere un compito complesso in più agenti invece di un singolo prompt lungo?

Quando il compito ha due o più modalità distinte che richiedono contesto diverso, formati di output diversi o gestione degli errori diversa. Vedi agenti basati su eventi vs. pianificati per il pattern.

Qual è la ragione più comune per cui un prompt che funzionava nei test fallisce in produzione?

Gli input di test non erano rappresentativi della distribuzione di produzione. Costruisci un set di test dal traffico di produzione reale, non da input immaginati.