Realtime API: progettare un agente vocale con latenza, strumenti e controlli
La guida Realtime di OpenAI spiega sessioni audio in tempo reale. Cosa misurare e quali limiti imporre prima di collegare voce, strumenti e dati di un utente.
Scritto da Redazione Daniel Vedovato · Revisionato il 21 luglio 2026
Articolo preparato con assistenza AI, verificato e revisionato da Daniel Vedovato.
La Realtime API di OpenAI consente interazioni audio e testuali a bassa latenza tramite una sessione persistente. La documentazione tratta modalità di connessione, eventi, input e output audio e uso di strumenti. Per chi costruisce un assistente vocale, il punto centrale non è soltanto ottenere una voce naturale. Bisogna governare turni di conversazione, interruzioni, conferme e azioni esterne in modo che l’utente capisca sempre che cosa sta accadendo.
Un agente vocale è più delicato di una chat tradizionale perché la voce accelera la richiesta. Una frase detta in fretta può essere ambigua, trascritta male o captata da rumore. Se il sistema può prenotare, inviare, cancellare o leggere dati, deve saper rallentare nel punto giusto.
Latenza percepita e latenza misurata
La latenza non è un solo numero. C’è il tempo dall’ultima parola dell’utente al rilevamento della fine turno, il tempo per ottenere la prima risposta, la durata della risposta sintetizzata e l’eventuale attesa di uno strumento. Un assistente può sembrare rapido se inizia a parlare subito, ma risultare frustrante se interrompe continuamente o se una chiamata esterna blocca la conversazione.
Registra le fasi separatamente. Questo permette di capire se un problema nasce dalla rete, dalla configurazione del rilevamento vocale, dal modello o da un servizio collegato. Senza questa distinzione, l’unica reazione possibile è tentare di cambiare tutto insieme.
| Evento | Metrica | Soglia da decidere nel prodotto |
|---|---|---|
| Fine turno | falsi stop e attese eccessive | quanto silenzio chiude il turno |
| Prima risposta | tempo al primo audio | fluidità percepita |
| Strumento | tempo e tasso di errore | quando informare l’utente |
| Interruzione | capacità di fermarsi | l’utente riprende il controllo |
| Trascrizione | errori su nomi e numeri | necessità di conferma |
Strumenti: separare conversazione e azione
La documentazione Realtime include il pattern per chiamare strumenti. Uno strumento non dovrebbe però essere un accesso generico alla rete o al database. Ogni funzione deve avere uno scopo stretto, parametri validati, autorizzazioni associate all’utente e risposta limitata a ciò che serve per il turno.
Prendiamo il caso di un assistente che modifica una prenotazione. L’agente può cercare disponibilità senza compiere un’azione irreversibile. Prima della modifica deve riepilogare data, ora, destinatario ed effetto della richiesta, poi chiedere una conferma esplicita. Se la trascrizione contiene un numero, una data o un indirizzo, ripetere il valore è un controllo di sicurezza, non un dettaglio di UX.
Il modello non deve mai ricevere credenziali con privilegi più ampi del necessario. Un backend controllato dal team deve eseguire l’azione dopo aver verificato sessione, autorizzazione e parametri. Log e audit devono registrare l’azione, non conservare audio o dati personali oltre il periodo necessario.
Progettare i fallimenti
La qualità di un agente vocale emerge quando qualcosa non funziona. Se la rete è lenta, dovrebbe dire che sta verificando invece di inventare una risposta. Se uno strumento restituisce errore, deve offrire un’alternativa chiara: riprovare, passare a un operatore o continuare via testo. Se l’audio non è comprensibile, deve chiedere di ripetere senza fingere di aver capito.
Queste regole vanno scritte nel flusso e testate con registrazioni sintetiche o con persone consenzienti. Accenti, rumore, sovrapposizioni e parole rare devono entrare nel set di prova. Una demo in una stanza silenziosa non è una valutazione sufficiente per supporto clienti, assistenza sanitaria o attività che coinvolgono denaro.
Privacy e consenso
L’audio può contenere dati personali e informazioni sensibili. L’utente deve sapere quando il microfono è attivo, cosa viene inviato e come interrompere la sessione. L’interfaccia deve mostrare stato di ascolto, elaborazione e risposta anche a chi preferisce leggere. Non affidare al solo audio comunicazioni importanti come termini, prezzi o cambiamenti di stato: offri una conferma scritta accessibile.
Il team deve inoltre definire conservazione, accessi e finalità dei dati vocali prima del pilota. Usare conversazioni reali per valutare il sistema senza una base chiara introduce un problema che nessuna ottimizzazione di latenza può risolvere.
Pilota responsabile
Inizia con un compito informativo e reversibile, per esempio spiegare orari o trovare documentazione pubblica. Limita durata della sessione, domini degli strumenti e numero di azioni. Misura completamento del compito, interruzioni corrette, errori di trascrizione, escalation umane e soddisfazione degli utenti, poi rivedi campioni con dati minimizzati.
Amplia l’autonomia solo quando il sistema dimostra di rispettare confini e di fallire in modo comprensibile. Il successo non è far parlare una voce il più possibile. È consentire a una persona di ottenere aiuto rapidamente mantenendo controllo, contesto e possibilità di correggere la macchina.