Konfigurer sessionen med session.update
På denne side
Opdateret 3. november 2026 baseret på xAI-siderne Speech to Speech og Text to Speech: 28 indbyggede stemmer, og
turn_detectionindstilles udelukkende via sintype(med valgfriidle_timeout_ms). Kilder: Speech to Speech · Text to Speech.
Konfigurer din voice agent
Når WebSocket-forbindelsen er åben, og du har modtaget hændelsen session.created, konfigurerer du sessionen ved at sende en session.update-besked. Her definerer du, hvordan din voice agent opfører sig: dens personlighed, dens stemme, de værktøjer, den kan bruge, og hvordan den registrerer taleskift.
Den fulde struktur for session.update
Her er et detaljeret konfigurationseksempel:
{
"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}
}
}
}
}
Indstillingerne i detaljer
Instruktioner (system-prompt)
Feltet instructions svarer til system-prompten i tekst-API’er: det definerer din voice agents personlighed, kontekst og begrænsninger. At skrive det indebærer dog en begrænsning, der er specifik for tale: korthed. Hvert token i prompten behandles før det første svar, og en vidtløftig prompt koster dig mærkbar latency, så snart opkaldet forbindes. Hold dig til det væsentlige, og flyt detaljerne over i din applikationslogik. Inden for dette stramme budget fortjener tre ting en plads. Tonen (formel, venlig, teknisk), fordi voice agenten bogstaveligt talt legemliggør dit brand i kundens øre. Sproget: angiv det („svar på engelsk”), ellers kan agenten følge brugerens eller spørgsmålets sprog. Og grænserne: hvad agenten kan gøre, og frem for alt, hvad den skal nægte eller videregive til et menneske, for på telefonen går et svar uden for scope afsted, før nogen kan gennemgå det.
Stemme
Indstillingen voice accepterer en af xAI’s 28 indbyggede stemmer (pr. 3. november 2026), som deles af voice agenten og text-to-speech, eller ID’et på en brugerdefineret stemme oprettet med Custom Voices API. Stemme-ID’er er ikke versalfølsomme: eve, Eve og EVE refererer alle til samme stemme. Alle stemmer taler alle understøttede sprog.
De fem oprindelige stemmer, som xAI beskriver dem:
- eve: energisk og munter, britisk accent
- ara: varm og venlig
- rex: selvsikker og klar
- sal: flydende og afbalanceret
- leo: autoritær og kraftfuld, britisk accent
Treogtyve nyere stemmer slutter sig til dem: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora og liora. Du kan hente den aktuelle liste med hver stemmes tone og anvendelsestilfælde fra GET /v1/tts/voices eller på xAI-siden Text to Speech.
Værktøjer
Arrayet tools definerer de værktøjer, agenten kan kalde under samtalen. Du kan kombinere flere typer: websøgning, X-søgning, brugerdefinerede funktioner, RAG-samlinger og MCP-servere. De følgende lektioner dækker værktøjer i detaljer.
Lydkonfiguration
Objektet audio indstiller input- og outputformater. Du kan bruge forskellige formater til input og output, hvis din arkitektur kræver det (f.eks. modtage G.711 fra et telefonsystem og sende PCM til en browser).
Opdater sessionen midt i samtalen
Du kan sende session.update flere gange under en samtale. Det giver dig mulighed for at ændre agentens adfærd løbende:
// Change the voice mid-conversation
ws.send(JSON.stringify({
type: "session.update",
session: {
voice: "Ara"
}
}));
// Add another tool
ws.send(JSON.stringify({
type: "session.update",
session: {
tools: [
{ type: "web_search" },
{ type: "x_search" }
]
}
}));
xAI-dokumentationen understøtter eksplicit ændringer midt i sessionen for flere indstillinger (transskriptionssprog, nøgleord, udtaleerstatninger, lydtransport), og session.updated bekræfter dem: tjek den for at bekræfte den konfiguration, der blev anvendt.
Vigtige pointer
session.updateer den første besked, du skal sende eftersession.created- Feltet
instructionsdefinerer agentens personlighed og begrænsninger - Der er 28 indbyggede stemmer tilgængelige (herunder eve, ara, rex, sal og leo) plus brugerdefinerede stemmer
- Lydkonfiguration og værktøjer kan tilpasses
- Du kan sende
session.updateflere gange for at ændre adfærd midt i samtalen