---
title: "Guida di stile per i prompt"
description: "Come scrivere e modificare il prompt di un agente vocale ThunderPhone: le verifiche della revisione del prompt delle linee guida, con gli ID citati nei relativi risultati."
---

{/*
  GENERATED FILE: do not edit by hand.
  Source: api/agents/prompt_style_guide.md
  Regenerate: python3 scripts/docs-freshness/generate_prompt_style_guide.py
  CI regenerates this page and fails on drift
  (scripts/docs-freshness/generators.d/50-prompt-style-guide.sh).
*/}

<Note>
  Questa è la guida rispetto a cui [prompt review](/api-reference/agents#review-a-prompt) verifica un prompt, e
  i suoi risultati citano gli ID seguenti. Gli agenti di programmazione connessi al
  [server MCP](/it/guides/thunderphone-mcp-server) leggono lo stesso testo come risorsa
  `thunderphone://guides/prompt-style`. Per modelli ed esempi, consulta la
  [guida ai prompt](/it/guides/prompting).
</Note>

Questa guida è destinata a chiunque scriva o modifichi il prompt di un agente vocale: una persona nel builder, Copilot o un agente
di programmazione che lavora tramite l'API. Lo strumento di revisione dei prompt la usa come criterio e cita i relativi ID delle linee guida (P1, W2
e così via).

Un chiamante ascolta l'agente una sola volta, al ritmo del parlato, e non può tornare indietro. L'agente legge il prompt a ogni
turno e ne riproduce fedelmente la formulazione. Entrambi questi aspetti determinano tutto ciò che segue.

## Struttura

**P1. Scrivilo come una persona istruirebbe una nuova addetta alla reception.** Una breve introduzione spiega chi è l'agente e per conto di chi lavora. La chiamata segue poi l'ordine in cui avviene: come inizia, quali informazioni raccogliere, cosa confermare,
come termina. Ogni regola si trova nella parte della chiamata a cui si applica. Chi legge dovrebbe poter chiedersi per ogni
paragrafo: "una persona che gestisce questa attività avrebbe potuto scriverlo?" Le informazioni da raccogliere comprendono ciò di cui l'attività ha bisogno per gestire
la richiesta, non solo chi sta chiamando e come contattarlo.

**P2. Titoli semplici, testo sotto.** Titoli come "Chi sei", "La chiamata", "Informazioni" e "Passaggio a un operatore"
sono utili. Una struttura in stile macchina non lo è: manuali di regole numerati, titoli in camelCase o simili al codice, lunghi elenchi
di regole con trattini, un riferimento agli strumenti all'inizio e rimandi come "vedi la sezione 4 di seguito". Gli elenchi vanno bene per
i dati che l'agente consulta (orari, prezzi, un indirizzo).

**P3. Modo di parlare, una sola volta e brevemente.** Il modo in cui l'agente parla durante l'intera chiamata (interventi brevi in prima persona,
tono cordiale, parole semplici; vedi S2) trova posto in un breve paragrafo vicino all'inizio. Tutto ciò che è specifico di una fase si trova in
quella fase.

**P4. Informazioni separate dal comportamento.** Orari, prezzi, sedi, politiche e altre informazioni vanno in una sezione informativa del
prompt o in una base di conoscenza, non disseminati nel flusso della chiamata. Cataloghi lunghi e FAQ appartengono a una base di conoscenza. L'agente
può dire solo le informazioni che gli sono state fornite.

## Contenuto

**C1. Principi e fatti, non copioni.** Descrivi cosa l'agente sta cercando di ottenere e cosa deve
sapere. Ometti ramificazioni del tipo "se il chiamante dice X, dì Y", risposte predefinite a domande previste e frasi
standard. Il saluto iniziale configurato è l'unico elemento di copione.

**C2. Una correzione enuncia il principio generale.** Quando una modifica al prompt risponde a un errore osservato, la modifica aggiunge
un principio generale o un fatto mancante, non una correzione per quel singolo caso. Le specificità della chiamata non riuscita (i relativi nomi,
numeri, parole esatte) restano fuori dal prompt.

**C3. Meglio togliere che aggiungere.** Quando un errore è riconducibile a una regola esistente troppo specifica, troppo ampia
o posizionata male, modifica o rimuovi quella regola invece di aggiungere una controregola accanto.

**C4. Alcune decisioni spettano alle impostazioni, non al prompt.** Queste sono impostazioni dell'agente e il testo del prompt che le riguarda viene
ignorato o entra in conflitto con esse: cosa viene detto mentre uno strumento è in esecuzione (frase di avvio dello strumento, frasi riempitive), verifiche
del silenzio e azione finale dopo il silenzio, ritmo della ripetizione per conferma, stile di cambio lingua,
avviso di registrazione e se parla per primo l'agente o il chiamante. Indica nel prompt il risultato desiderato
("conferma l'indirizzo email prima di salvarlo") e configura l'impostazione. Il saluto iniziale stesso viene scritto nel
prompt.

**C5. Gli esempi sono frasi che l'agente dirà.** L'agente copia la formulazione degli esempi quasi parola per parola, quindi ogni
esempio deve essere una frase completa e naturale da pronunciare, e alcuni esempi vari sono meglio di uno solo. Introducili come esempi ("Per
esempio, potresti dire ..."), non come frase obbligatoria. Etichette tronche come "Ancora corretto?" suonano secche una volta
pronunciate.

**C6. Nessun esempio tratto dalle chiamate dei nostri clienti.** Gli esempi descrivono il tipo di situazione in termini generali oppure
usano un'attività inventata.

**C7. Il prompt è per chi chiama, non riguarda la configurazione.** Chi chiama sente tutto ciò che dice il prompt una volta attivo, quindi omette note su configurazione, test o stato di conformità ("questa versione è per i test", "TEST" nel nome di una prenotazione, "finché gli accordi non sono firmati"). Omette inoltre disclaimer, limitazioni di responsabilità e riepiloghi finali che l'azienda non ha richiesto, come ciò che l'accettazione di un piano non determina o un riepilogo di ciò che non è ancora confermato. L'agente risponde a ciò che ha chiesto chi chiama e si ferma; l'azienda aggiunge una limitazione quando lo desidera. Un'informazione mancante o un limite del sistema viene espresso come ciò che fa l'agente ("per i prezzi, offri di essere richiamati dall'ufficio"), non come una nota sul fatto che non sia stata fornita o su come vengono registrate le richieste, e non rimane nulla della stesura, come un nome o un'intestazione fuori posto.

## Formulazione

**W1. Indica cosa fare, chiaramente, una sola volta.** Esprimi il comportamento desiderato come istruzione in parole comuni: "Ripeti il
numero dell'ordine cifra per cifra affinché il chiamante possa correggerlo." Dillo una sola volta, nel punto in cui si applica.

**W2. Nessuna enfasi.** Nessuna etichetta IMPORTANTE, NOTA o CRITICO, nessuna parola in maiuscolo per dare forza, nessun punto
esclamativo, nessuna coppia "Sbagliato:" e "Corretto:", nessun blocco su cosa non fare. Anche parole come "mai", "sempre" e "deve"
usate per dare forza rientrano qui. L'enfasi attira l'attenzione del modello su una regola e lo rende meno efficace nel resto della
chiamata. Quando l'agente ignora un'istruzione, rendila più chiara, più specifica o posizionala meglio, non più incisiva.

**W3. Correggi la struttura che causa un comportamento.** Prima di aggiungere una regola contro qualcosa che l'agente fa, individua
la formulazione o la struttura che lo porta lì: un modello che viene compilato letteralmente, un termine con due significati, un ramo if-else che un modello
veloce legge in modo approssimativo. Modifica quello.

**W4. Lo specifico è meglio del generico.** "Offri i due primi orari disponibili, poi chiedi quale va bene" è meglio di "aiuta con la
pianificazione". Le istruzioni vaghe producono comportamenti vaghi.

**W5. Verifica prima di chiedere informazioni.** Quando il chiamante nomina qualcosa che uno strumento di ricerca in sola lettura può verificare (un
prodotto, un ordine, una prenotazione esistente), l'agente verifica usando le parole fornite dal chiamante, poi pone una domanda di approfondimento solo
se il risultato lo richiede. "Controlla la disponibilità del prodotto nominato dal chiamante e comunicagli ciò che trovi" è meglio di "chiarisci
marca, taglia e variante, poi controlla la disponibilità": un agente a cui viene detto di chiarire prima continua a fare domande e la verifica non
viene mai eseguita. Questo vale solo per le ricerche. Prima di usare uno strumento che prenota, modifica, annulla o salva qualcosa, l'agente conferma
comunque i dettagli con il chiamante.

## Voce

**S1. Una domanda per turno, e la domanda conclude il turno.** Qualsiasi cosa detta dopo una domanda si sovrappone alla
risposta del chiamante. Metti qualsiasi spiegazione prima della domanda.

**S2. Turni brevi, in frasi complete e naturali.** Una o due frasi brevi, a meno che il chiamante non chieda dettagli.
Le opzioni espresse a voce sono limitate a poche. Breve significa poche parole, non frasi tronche: l'agente parla come una buona
receptionist al telefono, con frasi complete in prima persona, ad esempio "Prenoto subito per lei" oppure
"Ho segnato lunedì alle dieci." Frammenti in stile nota ("Prenoto per lei.", "Fatto.", "Annotato.") risultano sbrigativi
quando vengono pronunciati, mentre formule da email ("La informiamo che ...", "Cortesemente ...", "Spero sia utile") sembrano lette
anziché dette. Il paragrafo del prompt sul modo di parlare lo richiede in modo esplicito, ad esempio: "Mantieni ogni turno a una
o due frasi e parla in prima persona, come farebbe una receptionist al telefono."

**S3. Scrivi per l'ascolto.** In ciò che dice l'agente, evita markdown, simboli e notazioni che la voce leggerebbe in modo insolito
(barre, e commerciali, "@", ".com", separatori delle migliaia, numeri di telefono senza spazi). I fatti e i valori che l'agente passa
a uno strumento, come un indirizzo email o un numero di conto, restano nella loro esatta forma scritta; quando uno di essi deve anche essere
pronunciato ad alta voce, aggiungi accanto come viene detto invece di riscriverlo. Indica la pronuncia di nomi o acronimi insoliti,
e ascolta i nuovi termini con la voce dell'agente prima di mantenerli.

**S4. Conferma ciò che sarebbe costoso sbagliare.** Numeri, email, indirizzi e codici vengono riletti nella forma
in cui sono stati forniti, una volta, nella risposta subito dopo che il chiamante li comunica e prima della domanda successiva,
un valore per rilettura. Per impostazione predefinita, un nome viene acquisito come pronunciato, senza rileggerlo, e l'agente ne
chiede lo spelling solo quando è insolito o poco chiaro, e una sola volta. Quando l'azienda necessita del nome esatto, ad esempio
per confrontarlo con i propri registri o per una prenotazione a quel nome, il prompt lo indica e l'agente ripete lettera per lettera
il nome. Una rilettura offre al chiamante l'opportunità di correggere un valore, non è un controllo obbligatorio: un chiamante che
risponde con il dettaglio successivo o prosegue senza correggerlo lo ha accettato, e un valore accettato non viene chiesto di nuovo.
Un numero di telefono che l'azienda userà per richiamare o inviare un SMS è l'eccezione: la sua rilettura conclude il turno e attende
la risposta del chiamante. Un prompt che richiede la lettura cifra per cifra nomina solo i valori letti in quel modo (un numero di
telefono, un codice); un numero civico, un prezzo, un orario o una data vengono pronunciati nel modo in cui le persone li dicono.
Il prompt indica cosa confermare; la piattaforma regola il ritmo della rilettura.

## Iterazione

**I1. Esegui un test prima di mantenere una modifica.** Riproduci il set di sviluppo dell'agente sulla bozza modificata e confrontalo con la
versione attuale: quali esempi una modifica ha corretto e quali ha compromesso. Leggi le risposte come le sentirebbe un chiamante.
Tutto ciò che un chiamante noterebbe è un problema, non un dettaglio.

**I2. Il set di test viene controllato una volta.** Ottimizza solo sul set di sviluppo. Esegui il set di test quando una modifica è pronta e
riporta il risultato così com'è. Una modifica apportata dopo aver visto i risultati dei test richiede nuovi esempi di test.

**I3. Rifattorizza quando le correzioni si accumulano.** Un prompt che ha raccolto molte piccole correzioni si allontana da P1: le regole
si ripetono, entrano in conflitto o sono lontane dal passaggio che regolano. Quindi riscrivilo in questa forma, mantenendo ogni comportamento
richiesto. Elenca ogni comportamento come mantenuto, unito, riformulato o rimosso, e non rimuovere nulla senza dichiararlo. Riproduci il set di sviluppo
prima e dopo; un refactoring deve cambiare la formulazione, non il comportamento.

**I4. Controlla la configurazione prima del prompt.** Alcuni errori non dipendono dal prompt: interpretare male le lettere scandite è un limite dell'ascolto (prova l'ascolto Plus), una risposta lenta può dipendere dal livello di intelligenza o di ascolto oppure dall'impostazione di endpointing. Escludi problemi di configurazione prima di riscrivere il testo.
