Padroneggia gli eventi WebSocket
In questa pagina
Una conversazione fatta di eventi JSON
Sotto il cofano, uno scambio vocale con il Voice Agent è semplicemente un flusso di messaggi JSON che viaggiano in entrambe le direzioni attraverso la connessione WebSocket. Ogni messaggio possiede un campo type che ne definisce la natura. Finché non conosci questo vocabolario, il tuo client funziona a caso. Una volta appreso, sai esattamente dove intervenire per interrompere una risposta, visualizzare una trascrizione o recuperare un errore.
Gli eventi si dividono in due famiglie, a seconda della direzione del flusso. Quelli che invii guidano la sessione; quelli che ricevi ti informano su ciò che accade sul server.
Cosa invia la tua app
I tuoi messaggi in uscita coprono quattro esigenze: configurare la sessione, alimentare il buffer audio, gestire la cronologia della conversazione e controllare la generazione delle risposte.
| Evento | Scopo |
|---|---|
session.update | Configura o riconfigura la sessione (voce, istruzioni, strumenti, VAD, formato audio) |
input_audio_buffer.append | Invia un chunk audio codificato in base64, continuamente mentre l’utente parla |
input_audio_buffer.commit | Conferma il contenuto attuale del buffer come messaggio dell’utente; necessario solo in modalità manuale |
input_audio_buffer.clear | Svuota il buffer audio senza elaborarlo |
conversation.item.create | Aggiunge un elemento alla conversazione: un messaggio di testo, una cronologia precedente o il risultato di una chiamata di funzione |
conversation.item.delete | Elimina un elemento della conversazione tramite il suo ID |
response.create | Chiede al modello di generare una risposta; automatico in modalità VAD, esplicito in modalità manuale |
response.cancel | Annulla una risposta in corso di generazione |
Due di questi messaggi meritano un’attenzione particolare. conversation.item.create è il modo in cui inietti il contesto: è ciò che usi per ripristinare la cronologia di una chiamata precedente all’inizio di una nuova sessione. Per quanto riguarda input_audio_buffer.clear, torna utile quando l’utente non ha chiaramente detto nulla di rilevante (un colpo di tosse captato da un microfono troppo sensibile) e preferisci ripartire da un buffer pulito piuttosto che lasciare che il modello interpreti il rumore.
Cosa invia il server
Il flusso in entrata è più intenso, poiché fornisce un commento in tempo reale su ogni fase di elaborazione.
| Evento | Significato |
|---|---|
session.created | La sessione è aperta |
session.updated | È stato applicato un aggiornamento di configurazione |
conversation.created | La conversazione è impostata |
input_audio_buffer.speech_started | Il VAD rileva che l’utente ha iniziato a parlare |
input_audio_buffer.speech_stopped | Il VAD rileva che l’utente ha smesso di parlare |
input_audio_buffer.committed | Il buffer audio è stato confermato, dal VAD o manualmente |
response.created | Una risposta è in fase di generazione |
response.output_audio.delta | Un chunk audio della risposta, in base64 |
response.output_audio.done | L’audio della risposta è completo |
response.output_audio_transcript.delta | La trascrizione testuale dell’audio, in streaming |
response.done | La risposta è completamente terminata |
conversation.item.input_audio_transcription.completed | La trascrizione del messaggio dell’utente è disponibile |
response.text.delta | Testo in streaming, per risposte non vocali |
response.function_call_arguments.delta | Gli argomenti di una chiamata di funzione, in streaming |
response.function_call_arguments.done | La chiamata di funzione è completa e pronta per l’esecuzione |
error | Si è verificato un errore; la maggior parte degli errori è recuperabile |
Quest’ultimo richiede un avvertimento. Ricevere error non significa che la sessione sia persa. Secondo il riferimento xAI, la maggior parte degli errori è recuperabile e la sessione rimane aperta, quindi un client che chiude la connessione al primo error interrompe una conversazione che avrebbe potuto continuare. Registra l’errore, informa l’utente se necessario, ma mantieni il socket aperto.
Lo scheletro di un client
In pratica, tutto si riduce a uno switch su msg.type. Ecco la struttura minima di un client JavaScript:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Invia session.update con la configurazione
break;
case "input_audio_buffer.speech_started":
// L'utente sta parlando: ferma l'audio della risposta in riproduzione
break;
case "response.output_audio.delta":
// Decodifica il base64 e riproduci l'audio
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Esegui la funzione e invia indietro il risultato
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent error:", msg.error);
break;
}
};
Quattro rami sono sufficienti per far funzionare un agent: configura all’apertura della sessione, reagisci quando l’utente inizia a parlare, riproduci l’audio in arrivo ed esegui le funzioni. Gli altri eventi arricchiscono l’interfaccia e possono attendere una seconda iterazione.
La parte delicata: le interruzioni
Il barge-in, ovvero quando l’utente inizia a parlare mentre l’agent sta ancora rispondendo, è il punto in cui un’implementazione approssimativa mostra i suoi limiti. Il server annulla automaticamente la risposta corrente e inizia a generarne una nuova basandosi su ciò che ha appena ascoltato. Tuttavia, mentre il server ha smesso di inviare dati, la tua app conserva ancora diversi secondi di audio già ricevuto nel suo buffer di output.
Se non fai nulla, l’utente continua a sentire la frase che ha appena interrotto mentre ci parla sopra, e l’agent dà l’impressione di non ascoltare. Quindi, non appena ricevi speech_started, ferma l’audio in riproduzione, svuota il buffer di output per evitare di riprodurre suoni obsoleti e lascia che il server elabori il nuovo input. Questi due passaggi richiedono poche righe di codice e fanno tutta la differenza tra un agent che puoi interrompere e uno che parla nel vuoto.
Punti chiave
- Gli eventi del client coprono configurazione, invio audio, gestione della conversazione e controllo delle risposte
- Gli eventi del server segnalano rilevamento vocale, chunk audio, trascrizioni e chiamate di funzione
- Il VAD gestisce automaticamente le interruzioni (barge-in)
- La maggior parte degli eventi
errorè recuperabile: non chiudere la connessione, gestisci l’errore - In modalità manuale, devi chiamare esplicitamente
commite poiresponse.create