Een voicesessie configureren
Op deze pagina
Bijgewerkt op 3 november 2026, gebaseerd op de xAI-pagina Speech to Speech en de handleiding voor voice-prompting. Bronnen: Speech to Speech · Prompting Guide.
Het bericht dat alles bepaalt: session.update
Zodra de WebSocket-verbinding tot stand is gebracht, gebeurt er nog niets. Het bericht session.update geeft de agent zijn karakter: de stem die hij gebruikt, de instructies die hij volgt, hoe hij beurtwisseling detecteert en welke tools hij mag aanroepen. Zie het als de geboorteakte van de sessie. Alles wat volgt in het gesprek, vloeit hieruit voort.
{
"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" }
]
}
}
De server bevestigt dit met een session.updated-gebeurtenis. U hoeft dit bericht niet slechts één keer te verzenden. U kunt het midden in een gesprek opnieuw sturen om een instelling wijzigen, bijvoorbeeld om van stem te wisselen wanneer het gesprek van verkoop naar technische ondersteuning gaat, zonder de verbinding ooit te verbreken.
Schrijf instructies voor het oor, niet voor het oog
Het veld instructions vervult de rol van de systeemprompt. Gebruik het om de persoonlijkheid van de agent vast te leggen (formeel, informeel, technisch), de onderwerpen die hij mag behandelen, de beperkingen voor zijn antwoorden (lengte, formaat, taal) en de zakelijke context die hij nodig heeft: uw bedrijfsnaam, assortiment en interne procedures.
Het addertje onder het gras is dat wat een goede geschreven prompt maakt, vaak leidt tot een slechte voice-agent. Als u het model zijn gang laat, schrijft het antwoorden van tien regels. Hardop voorgelezen slepen deze aan en haakt de gebruiker af voordat het einde is bereikt. Vraag daarom expliciet om korte, directe antwoorden. Als uw app in één taal werkt, geef dit dan aan; anders kan de agent overschakelen om het accent van de beller na te bootsen. Vertel de agent ook wat hij moet doen als hij iets niet begrijpt: een instructie als “stel een verduidelijkende vraag in plaats van te raden” voorkomt dat een verkeerd verstaan ordernummer een zinloze zoekopdracht activeert. De xAI-handleiding voor voice-prompting stelt zelfs een structuur in vijf delen voor (rol en persona, doel, gespreksverloop, bewaking en escalatie, stemstijl) en adviseert één of twee korte zinnen per beurt, tenzij de beller om meer details vraagt.
Beurtdetectie
Het blok turn_detection bepaalt wie wanneer aan het woord is. De documentatie van xAI biedt hiervoor slechts twee instellingen. De eerste is type. In de modus "server_vad" detecteert de server zelfstandig het einde van elke uiting, legt de audio vast, start het antwoord en handelt onderbrekingen af. Uw enige taak is het verzenden van audio met input_audio_buffer.append. De tweede instelling, idle_timeout_ms, is optioneel. Als de gebruiker na een antwoord gedurende dat aantal milliseconden stil blijft, vraagt de server om een reactie. Dit herhaalt zich na elke nieuwe stilte van dezelfde duur.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Er is geen gevoeligheidsdrempel of stilte-duur om af te stellen. De parameters threshold, silence_duration_ms en prefix_padding_ms die u ziet in voorbeelden voor de OpenAI Realtime API, komen niet voor in de documentatie van xAI.
Als het automatische gedrag niet bevalt, stelt u het type in op null en neemt u zelf de controle. Het is dan aan u om de audio te bufferen met input_audio_buffer.append, de beurt expliciet vast te leggen met input_audio_buffer.commit en de generatie te activeren met response.create. De handmatige modus is de juiste keuze voor een push-to-talk-interface, of wanneer u nauwkeurige controle wilt over wanneer de agent spreekt.
Kies het juiste audioformaat
Het blok audio stelt de input- en outputformaten onafhankelijk van elkaar in:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Er worden vier typen geaccepteerd. Als u er geen opgeeft, krijgt u PCM op 24.000 Hz:
| Type | Codering | Samplefrequentie |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (Noord-Amerikaanse telefonie) | Alleen 8000 Hz |
audio/pcma | G.711 A-law (Europese telefonie) | Alleen 8000 Hz |
audio/opus | Opus, één pakket per bericht | 24000 Hz |
Uw leveringskanaal bepaalt de keuze. Een webapp in een browser doet het prima met PCM op 24.000 Hz, een goede balans tussen waargenomen kwaliteit en bandbreedte. Bij een integratie met een SIP-telefoon heeft u geen keuze: het netwerk vervoert G.711 op 8.000 Hz. Het opleggen van een hoger kwaliteitsformaat voegt alleen een zinloze conversie toe.
Geef de agent tools
De array tools somt op wat de agent tijdens het gesprek mag aanroepen. U kunt verschillende soorten binnen dezelfde sessie mengen:
{
"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"]
}
}
]
}
U levert de gereedschapskist; de agent kiest het gereedschap. Naarmate het gesprek vordert, besluit hij dat een vraag over het nieuws een webzoekopdracht vereist, terwijl een ordernummer een aanroep van get_order_status rechtvaardigt. Uw taak bestaat dus minder uit het orkestreren van aanroepen en meer uit het helder beschrijven van elke tool, zodat de agent de juiste keuze maakt.
Belangrijkste punten
- Het bericht
session.updateconfigureert de stem, instructies, VAD en tools - Server-side VAD (
server_vad) detecteert beurten en handelt onderbrekingen af;idle_timeout_msis de enige instelling - Handmatige modus (
turn_detection.typeingesteld opnull) geeft u nauwkeurige controle, bijvoorbeeld bij push-to-talk - Audioformaten PCM, G.711 en Opus dekken zowel web- als telefonietoepassingen
- U kunt de configuratie midden in een sessie wijzigen zonder de verbinding te verbreken