Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Padroneggia gli eventi WebSocket

Lezione 4 di 14 Aggiornata il 29 luglio 2026 Intermedio
In questa pagina
  1. Una conversazione fatta di eventi JSON
  2. Cosa invia la tua app
  3. Cosa invia il server
  4. Lo scheletro di un client
  5. La parte delicata: le interruzioni
  6. Punti chiave

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.

EventoScopo
session.updateConfigura o riconfigura la sessione (voce, istruzioni, strumenti, VAD, formato audio)
input_audio_buffer.appendInvia un chunk audio codificato in base64, continuamente mentre l’utente parla
input_audio_buffer.commitConferma il contenuto attuale del buffer come messaggio dell’utente; necessario solo in modalità manuale
input_audio_buffer.clearSvuota il buffer audio senza elaborarlo
conversation.item.createAggiunge un elemento alla conversazione: un messaggio di testo, una cronologia precedente o il risultato di una chiamata di funzione
conversation.item.deleteElimina un elemento della conversazione tramite il suo ID
response.createChiede al modello di generare una risposta; automatico in modalità VAD, esplicito in modalità manuale
response.cancelAnnulla 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.

EventoSignificato
session.createdLa sessione è aperta
session.updatedÈ stato applicato un aggiornamento di configurazione
conversation.createdLa conversazione è impostata
input_audio_buffer.speech_startedIl VAD rileva che l’utente ha iniziato a parlare
input_audio_buffer.speech_stoppedIl VAD rileva che l’utente ha smesso di parlare
input_audio_buffer.committedIl buffer audio è stato confermato, dal VAD o manualmente
response.createdUna risposta è in fase di generazione
response.output_audio.deltaUn chunk audio della risposta, in base64
response.output_audio.doneL’audio della risposta è completo
response.output_audio_transcript.deltaLa trascrizione testuale dell’audio, in streaming
response.doneLa risposta è completamente terminata
conversation.item.input_audio_transcription.completedLa trascrizione del messaggio dell’utente è disponibile
response.text.deltaTesto in streaming, per risposte non vocali
response.function_call_arguments.deltaGli argomenti di una chiamata di funzione, in streaming
response.function_call_arguments.doneLa chiamata di funzione è completa e pronta per l’esecuzione
errorSi è 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 commit e poi response.create