Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configura la sessione con session.update

Lezione 3 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Configura il tuo agente vocale
  2. La struttura completa di session.update
  3. Le impostazioni nel dettaglio
  4. Aggiorna la sessione a conversazione in corso
  5. Punti chiave

Aggiornato il 3 novembre 2026, sulla base delle pagine Speech to Speech e Text to Speech di xAI: 28 voci integrate e turn_detection impostato solo dal suo type (con idle_timeout_ms opzionale). Fonti: Speech to Speech · Text to Speech.

Configura il tuo agente vocale

Una volta stabilita la connessione WebSocket e ricevuto l’evento session.created, configura la sessione inviando un messaggio session.update. È qui che definisci il comportamento del tuo agente vocale: la sua personalità, la sua voce, gli strumenti che può utilizzare e il modo in cui rileva i turni di parola.

La struttura completa di session.update

Ecco un esempio di configurazione dettagliato:

{
  "type": "session.update",
  "session": {
    "instructions": "You are a professional voice assistant for a law firm. Answer concisely and precisely. Use a formal tone.",
    "voice": "Rex",
    "tools": [
      {"type": "web_search"},
      {
        "type": "function",
        "name": "look_up_case",
        "description": "Looks up a client case by number",
        "parameters": {
          "type": "object",
          "properties": {
            "case_number": {
              "type": "string",
              "description": "Client case number"
            }
          },
          "required": ["case_number"]
        }
      }
    ],
    "turn_detection": {
      "type": "server_vad"
    },
    "audio": {
      "input": {
        "format": {"type": "audio/pcm", "rate": 24000}
      },
      "output": {
        "format": {"type": "audio/pcm", "rate": 24000}
      }
    }
  }
}

Le impostazioni nel dettaglio

Istruzioni (prompt di sistema)

Il campo instructions equivale al prompt di sistema nelle API testuali: definisce la personalità, il contesto e i vincoli del tuo agente vocale. La scrittura di questo campo comporta però un vincolo specifico per la voce: la brevità. Ogni token del prompt viene elaborato prima della prima risposta e un prompt prolisso ti costa una latenza percepibile nel momento in cui la chiamata si connette. Attieniti all’essenziale e sposta i dettagli nella logica della tua applicazione. All’interno di quel budget ristretto, tre elementi meritano un posto. Il tono (formale, amichevole, tecnico), perché l’agente vocale incarna letteralmente il tuo brand nell’orecchio del cliente. La lingua: specificala («rispondi in inglese»), altrimenti l’agente potrebbe seguire la lingua dell’utente o della domanda. E i limiti: cosa può fare l’agente e, soprattutto, cosa deve rifiutare o inoltrare a un operatore umano, perché al telefono una risposta fuori scope viene erogata prima che chiunque possa revisionarla.

Voce

L’impostazione voice accetta una delle 28 voci integrate di xAI (al 3 novembre 2026), condivise dall’agente vocale e dal text-to-speech, oppure l’ID di una voce personalizzata creata con le Custom Voices API. Gli ID delle voci non distinguono tra maiuscole e minuscole: eve, Eve ed EVE si riferiscono tutti alla stessa voce. Ogni voce parla tutte le lingue supportate.

Le cinque voci originali, così come le descrive xAI:

  • eve: energica e ottimista, accento britannico
  • ara: calda e amichevole
  • rex: sicura e chiara
  • sal: fluida ed equilibrata
  • leo: autorevole e potente, accento britannico

A queste si aggiungono ventitré voci più recenti: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora e liora. Puoi ottenere l’elenco attuale, con il tono e i casi d’uso di ciascuna voce, tramite GET /v1/tts/voices o sulla pagina Text to Speech di xAI.

Strumenti

L’array tools definisce gli strumenti che l’agente può chiamare durante la conversazione. Puoi combinare diversi tipi: ricerca web, ricerca su X, funzioni personalizzate, collezioni RAG e server MCP. Le prossime lezioni trattano gli strumenti nel dettaglio.

Configurazione audio

L’oggetto audio imposta i formati di input e output. Puoi utilizzare formati diversi per input e output se la tua architettura lo richiede (ad esempio, ricevendo G.711 da un sistema telefonico e inviando PCM a un browser).

Aggiorna la sessione a conversazione in corso

Puoi inviare session.update più volte durante una conversazione. Questo ti permette di modificare il comportamento dell’agente al volo:

// Cambia la voce a conversazione in corso
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    voice: "Ara"
  }
}));

// Aggiungi un altro strumento
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [
      { type: "web_search" },
      { type: "x_search" }
    ]
  }
}));

La documentazione di xAI supporta esplicitamente le modifiche a metà sessione per diverse impostazioni (lingua di trascrizione, parole chiave, sostituzioni di pronuncia, trasporto audio) e session.updated ne conferma l’avvenuta applicazione: controllalo per verificare la configurazione applicata.

Punti chiave

  • session.update è il primo messaggio da inviare dopo session.created
  • Il campo instructions definisce la personalità e i vincoli dell’agente
  • Sono disponibili 28 voci integrate (tra cui eve, ara, rex, sal e leo), oltre alle voci personalizzate
  • La configurazione audio e gli strumenti sono personalizzabili
  • Puoi inviare session.update più volte per modificare il comportamento a conversazione in corso