Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configura una sessione vocale

Lezione 2 di 14 Aggiornata il 3 novembre 2026 Intermedio
In questa pagina
  1. Il messaggio che definisce tutto: session.update
  2. Scrivi istruzioni per l’orecchio, non per l’occhio
  3. Rilevamento dei turni
  4. Scegli il formato audio corretto
  5. Fornisci strumenti all’agente
  6. Punti chiave

Aggiornato il 3 novembre 2026, sulla base della pagina Speech to Speech di xAI e della guida al prompting vocale. Fonti: Speech to Speech · Prompting Guide.

Il messaggio che definisce tutto: session.update

Una volta stabilita la connessione WebSocket, non succede ancora nulla. Il messaggio session.update è ciò che conferisce all’agente la sua personalità: la voce che utilizza, le istruzioni che segue, il modo in cui rileva i turni di parola e quali strumenti può invocare. Consideralo il certificato di nascita della sessione. Tutto il resto della conversazione ne deriva.

{
  "type": "session.update",
  "session": {
    "instructions": "You are a professional voice assistant for an e-commerce company. Keep your answers short and help customers with their orders.",
    "voice": "Ara",
    "turn_detection": {
      "type": "server_vad"
    },
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    },
    "tools": [
      { "type": "web_search" }
    ]
  }
}

Il server conferma la ricezione con un evento session.updated. Non sei obbligato a inviare questo messaggio una sola volta. Puoi inviarlo nuovamente nel mezzo della conversazione per modificare un’impostazione al volo, ad esempio per cambiare voce quando la chiamata passa dal reparto vendite al supporto tecnico, senza mai interrompere la connessione.

Scrivi istruzioni per l’orecchio, non per l’occhio

Il campo instructions svolge il ruolo di prompt di sistema. Usalo per definire la personalità dell’agente (formale, informale, tecnica), gli argomenti che può trattare, i vincoli sulle sue risposte (lunghezza, formato, lingua) e il contesto aziendale necessario: il nome della tua azienda, la gamma di prodotti e le procedure interne.

Il problema è che ciò che rende efficace un prompt scritto spesso crea un agente vocale scadente. Se lasciato a se stesso, un modello genera risposte lunghe dieci righe. Lette ad alta voce, risultano prolisse e l’utente si distrae prima della fine. Chiedi quindi esplicitamente risposte brevi e dirette. Se la tua applicazione funziona in una sola lingua, specificala, altrimenti l’agente potrebbe cambiare lingua per adattarsi all’accento dell’interlocutore. Spiegagli inoltre cosa fare quando non capisce: un’istruzione come “fai una domanda di chiarimento invece di indovinare” evita che un numero d’ordine frainteso inneschi una ricerca inutile. La guida al prompting vocale di xAI suggerisce persino una struttura in cinque parti (ruolo e persona, obiettivo, flusso conversazionale, limiti ed escalation, stile vocale) e raccomanda una o due frasi brevi per turno, a meno che l’interlocutore non richieda maggiori dettagli.

Rilevamento dei turni

Il blocco turn_detection decide chi parla e quando; la documentazione xAI prevede solo due impostazioni per questo scopo. La prima è type. Nella modalità "server_vad", il server rileva autonomamente la fine di ogni enunciato, elabora l’audio, avvia la risposta e gestisce le interruzioni: tutto ciò che devi fare è inviare l’audio con input_audio_buffer.append. La seconda impostazione, idle_timeout_ms, è opzionale. Se l’utente rimane in silenzio per quel numero di millisecondi dopo una risposta, il server lo sollecita a parlare, ripetendo l’operazione dopo ogni nuovo periodo di silenzio della stessa durata.

{
  "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}

Non esiste alcuna soglia di sensibilità o durata del silenzio da regolare. I parametri threshold, silence_duration_ms e prefix_padding_ms che potresti vedere negli esempi scritti per le API Realtime di OpenAI non compaiono nella documentazione xAI.

Se il comportamento automatico non ti soddisfa, imposta il tipo su null e prendi il controllo. Spetterà quindi a te bufferizzare l’audio con input_audio_buffer.append, confermare esplicitamente il turno con input_audio_buffer.commit e attivare la generazione con response.create. La modalità manuale è la scelta giusta per un’interfaccia push-to-talk o ogni volta che desideri un controllo preciso su quando l’agente parla.

Scegli il formato audio corretto

Il blocco audio imposta i formati di input e output in modo indipendente:

{
  "audio": {
    "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
    "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
  }
}

Sono accettati quattro tipi. Se non ne specifichi uno, ottieni PCM a 24.000 Hz:

TipoCodificaFrequenze di campionamento
audio/pcmPCM Linear16, little-endian8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
audio/pcmuG.711 mu-law (telefonia nordamericana)Solo 8000 Hz
audio/pcmaG.711 A-law (telefonia europea)Solo 8000 Hz
audio/opusOpus, un pacchetto per messaggio24000 Hz

È il tuo canale di distribuzione a decidere. Un’app web nel browser funziona bene con PCM a 24.000 Hz, un buon equilibrio tra qualità percepita e larghezza di banda. Un’integrazione con telefono SIP non ha scelta: la rete trasporta G.711 a 8.000 Hz e forzare un formato di qualità superiore aggiungerebbe solo una conversione inutile.

Fornisci strumenti all’agente

L’array tools elenca ciò che l’agente può chiamare durante la conversazione; puoi mescolare diversi tipi nella stessa sessione:

{
  "tools": [
    { "type": "web_search" },
    { "type": "x_search", "allowed_x_handles": ["gaborit_music"] },
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

Tu fornisci la cassetta degli attrezzi; l’agente sceglie lo strumento. Mentre la conversazione prosegue, decide che una domanda sulle notizie richiede una ricerca web, mentre un numero d’ordine richiede get_order_status. Il tuo compito consiste quindi meno nell’orchestrare le chiamate e più nel descrivere chiaramente ogni strumento, affinché l’agente faccia la scelta giusta.

Punti chiave

  • Il messaggio session.update configura la voce, le istruzioni, il VAD e gli strumenti
  • Il VAD lato server (server_vad) rileva i turni e gestisce le interruzioni; idle_timeout_ms è l’unica impostazione disponibile
  • La modalità manuale (turn_detection.type impostato su null) offre un controllo preciso, ad esempio con il push-to-talk
  • I formati audio PCM, G.711 e Opus coprono sia i casi d’uso web che quelli telefonici
  • Puoi modificare la configurazione a metà sessione senza interrompere la connessione