Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Costruisci un assistente vocale interattivo

Lezione 10 di 14 Aggiornata il 29 luglio 2026 Intermedio
In questa pagina
  1. Dal prototipo all’assistente vocale in produzione
  2. L’assistente web nel browser
  3. L’assistente mobile
  4. Il chiosco interattivo
  5. Pattern condivisi da tutte e tre le architetture
  6. Punti chiave

Dal prototipo all’assistente vocale in produzione

Sai configurare una sessione Voice Agent e generare audio con il TTS. Ora non ti resta che assemblare questi mattoni in un prodotto capace di reggere l’urto degli utenti reali. Tre architetture ricorrono spesso (browser, mobile e chiosco interattivo), e ciascuna impone vincoli tecnici ben prima che la qualità del modello entri in gioco.

L’assistente web nel browser

È il punto di partenza più comune: un pulsante del microfono in un’app esistente, l’utente parla e l’assistente risponde a voce. Il ciclo tecnico funziona così:

  1. L’utente clicca il pulsante: avvii la cattura audio con MediaRecorder o AudioWorklet
  2. L’audio catturato viene convertito in PCM base64 e inviato al Voice Agent tramite WebSocket
  3. Il VAD lato server rileva la fine del discorso e genera una risposta
  4. I chunk audio della risposta arrivano tramite response.output_audio.delta
  5. Li decodifichi e li riproduci con AudioContext

Il problema raramente nasce da questo ciclo, ma dal browser stesso. Safari richiede che AudioContext venga creato all’interno di un gestore eventi utente. Crealo al primo clic sul pulsante del microfono, non al caricamento della pagina, altrimenti otterrai un contesto sospeso e silenzio totale. La politica di autoplay va nella stessa direzione: nessuna riproduzione audio può iniziare senza un’interazione utente precedente, il che esclude un saluto che si riproduce automaticamente quando qualcuno atterra sulla pagina. Per i formati di output, attieniti a PCM o MP3, poiché i browser non possono riprodurre nativamente mulaw e alaw. E la chiave API non deve mai finire nel codice client: resta sul tuo server, mentre il browser utilizza un token effimero (lezione 13).

Anche la cattura richiede messa a punto:

const stream = await navigator.mediaDevices.getUserMedia({
  audio: {
    sampleRate: 24000,
    channelCount: 1,
    echoCancellation: true,
    noiseSuppression: true
  }
});

Cancellazione dell’eco e soppressione del rumore non sono optional. Senza di esse, il microfono capta la risposta dell’assistente uscita dagli altoparlanti, il VAD la scambia per voce dell’utente e l’agente continua a interrompersi da solo. Fai sempre i test senza cuffie: è la configurazione in cui il feedback si manifesta.

L’assistente mobile

Con React Native o Flutter, il principio resta lo stesso, ma l’ambiente si fa più ostico. Usa le API di cattura native (AVAudioEngine su iOS, AudioRecord su Android) invece di un’astrazione generica: la qualità del segnale in ingresso influisce direttamente sul riconoscimento. Implementa un ricollegamento automatico, perché il WebSocket cade non appena l’app passa in background, cosa che succede nel momento in cui arriva una notifica durante una conversazione.

Due aspetti sfuggono spesso ai test interni. Il primo è il routing audio: altoparlante o auricolare, il comportamento atteso cambia a seconda che l’utente tenga il telefono all’orecchio o lo appoggi su un tavolo. Il secondo è il Bluetooth, la cui latenza si somma a quella della rete e del modello; una conversazione fluida con il microfono integrato può diventare scattosa con gli auricolari wireless.

Il chiosco interattivo

Per un chiosco in un negozio, alla reception di un hotel o in una galleria museale, il vincolo dominante diventa l’ambiente sonoro. Un microfono cardioide e direzionale limita la captazione alla persona che sta davanti al chiosco. Non contare su un’impostazione di sensibilità per filtrare la folla: il rilevamento del turno del Voice Agent espone solo type e idle_timeout_ms, senza alcuna soglia da alzare. Quando il locale è molto rumoroso, come il concourse di una stazione ferroviaria o una fiera, il push-to-talk con un pulsante fisico è più affidabile di qualsiasi rilevamento automatico.

Infine, ricorda di chiudere le sessioni dopo due o tre minuti di inattività. Altrimenti, un visitatore che se ne va a metà conversazione lascia una sessione aperta che consuma le tue risorse e occupa uno dei tuoi slot concorrenti.

Pattern condivisi da tutte e tre le architetture

Il Voice Agent mantiene la cronologia della conversazione per l’intera sessione. Puoi prepararlo prima della prima parola iniettando contesto utile, come l’identità del cliente loggato o un ordine in corso, con conversation.item.create:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "system",
    "content": [
      {
        "type": "text",
        "text": "The signed-in customer is Sarah Miller, customer number C-4521. She has an order in progress, CMD-8834."
      }
    ]
  }
}

L’agente smette così di chiedere all’utente informazioni che la tua app possiede già, risparmiando una decina di secondi a ogni conversazione.

Per far parlare l’assistente per primo, inserisci un messaggio iniziale e poi attiva la risposta:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [{ "type": "text", "text": "Hello" }]
  }
}

Un { "type": "response.create" } inviato subito dopo attiva il saluto.

Resta il feedback visivo, spesso gestito per ultimo nonostante pesi molto sulla percezione del prodotto. Mostra un indicatore mentre l’agente parla (un’onda sonora, un avatar animato) e un altro mentre stai catturando l’audio. Senza quel segnale, gli utenti non sanno se devono parlare, se vengono ascoltati o se l’app si è bloccata, e finiscono per parlare sopra l’agente.

Punti chiave

  • Tre architetture principali: web, mobile e chiosco, ognuna con i propri vincoli
  • L’audio nel browser richiede cura (AudioContext di Safari, politica di autoplay)
  • Precompila il contesto della conversazione con conversation.item.create per personalizzare l’esperienza
  • Un saluto e un feedback visivo migliorano significativamente l’esperienza utente