Konfigurace hlasové relace
Na této stránce
Aktualizováno 3. listopadu 2026 na základě stránky xAI Speech to Speech a průvodce hlasovými prompty. Zdroje: Speech to Speech · Prompting Guide.
Zpráva, která vše nastavuje: session.update
Jakmile je WebSocket připojení otevřené, zatím se nic neděje. Zpráva session.update je tím, co agentovi dodá jeho charakter: hlas, kterým mluví, pokyny, kterými se řídí, způsob detekce střídání řečníků a nástroje, které smí volat. Ber to jako rodný list relace. Všechno ostatní v konverzaci z toho vyplývá.
{
"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" }
]
}
}
Server ji potvrdí událostí session.updated. Tuto zprávu nemusíš posílat jen jednou. Můžeš ji poslat znovu uprostřed konverzace a změnit nastavení za chodu, například přepnout hlasy, když hovor přejde z prodeje na technickou podporu, aniž bys musel přerušit připojení.
Piš pokyny pro ucho, ne pro oko
Pole instructions hraje roli systémového promptu. Použij ho k nastavení osobnosti agenta (formální, neformální, technický), témat, kterým se smí věnovat, omezení jeho odpovědí (délka, formát, jazyk) a obchodního kontextu, který potřebuje: název tvé firmy, sortiment produktů a interní postupy.
Háček je v tom, že to, co funguje jako dobrý písemný prompt, často dělá špatného hlasového agenta. Pokud ho necháš napospas, model napíše odpovědi dlouhé deset řádků. Čteny nahlas se táhnou a uživatel přestane poslouchat dřív, než skončí. Proto explicitně požaduj krátké a přímé odpovědi. Pokud tvoje aplikace funguje v jediném jazyce, řekni který, jinak může agent přepnout, aby odpovídal přízvuku volajícího. A řekni mu, co má dělat, když nerozumí: pokyn typu „místo hádání se zeptej na upřesnění“ zajistí, že špatně zaslechnuté číslo objednávky nespustí zbytečné hledání. Průvodce hlasovými prompty od xAI dokonce navrhuje pětidílnou strukturu (role a persona, cíl, průběh konverzace, ochranná opatření a eskalace, styl hlasu) a doporučuje jednu až dvě krátké věty na každou repliku, pokud si volající nevyžádá více podrobností.
Detekce střídání řečníků
Blok turn_detection rozhoduje o tom, kdo a kdy mluví, a dokumentace xAI pro něj nabízí pouze dvě nastavení. Prvním je type. V režimu "server_vad" server sám detekuje konec každé výpovědi, potvrdí audio, spustí odpověď a zpracuje přerušení: ty jen posíláš audio pomocí input_audio_buffer.append. Druhým nastavením je volitelné idle_timeout_ms. Pokud uživatel po odpovědi mlčí po daný počet milisekund, server ho vyzve k reakci, a to opakuje po každém dalším tichu stejné délky.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Neexistuje žádný práh citlivosti ani doba ticha k ladění. Parametry threshold, silence_duration_ms a prefix_padding_ms, které uvidíš v příkladech psaných pro OpenAI Realtime API, se v dokumentaci xAI nevyskytují.
Pokud ti automatické chování nevyhovuje, nastav typ na null a převezmi kontrolu. Pak je na tobě, abys bufferoval audio pomocí input_audio_buffer.append, explicitně potvrdil repliku pomocí input_audio_buffer.commit a spustil generování pomocí response.create. Ruční režim je správnou volbou pro rozhraní typu „stiskni a mluv“ (push-to-talk) nebo kdykoli chceš mít přesnou kontrolu nad tím, kdy agent promluví.
Vyber správný audio formát
Blok audio nastavuje vstupní a výstupní formáty nezávisle na sobě:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Jsou akceptovány čtyři typy. Pokud žádný nezadáš, získáš PCM na 24 000 Hz:
| Typ | Kódování | Vzorkovací frekvence |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (severoamerická telefonie) | Pouze 8000 Hz |
audio/pcma | G.711 A-law (evropská telefonie) | Pouze 8000 Hz |
audio/opus | Opus, jeden paket na zprávu | 24000 Hz |
Rozhoduje tvůj doručovací kanál. Webová aplikace v prohlížeči si dobře poradí s PCM na 24 000 Hz, což je dobrý kompromis mezi vnímanou kvalitou a šířkou pásma. Integrace SIP telefonu nemá na výběr: síť přenáší G.711 na 8 000 Hz a vynucování formátu vyšší kvality by jen přidalo zbytečnou konverzi.
Dej agentovi nástroje
Pole tools uvádí, co může agent během konverzace volat, a v jedné relaci můžeš kombinovat různé druhy:
{
"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"]
}
}
]
}
Ty poskytuješ sadu nástrojů; agent si nástroj vybírá. Jak konverzace postupuje, rozhodne se, že otázka na zprávy vyžaduje webové hledání, zatímco číslo objednávky volá funkci get_order_status. Tvá práce tedy není tolik o orchestraci volání, ale spíše o jasném popisu každého nástroje, aby se agent rozhodl správně.
Klíčové poznatky
- Zpráva
session.updatekonfiguruje hlas, pokyny, VAD a nástroje - VAD na straně serveru (
server_vad) detekuje střídání řečníků a zpracovává přerušení;idle_timeout_msje jediným nastavením - Ruční režim (
turn_detection.typenastaveno nanull) ti dává přesnou kontrolu, například u rozhraní typu push-to-talk - Audio formáty PCM, G.711 a Opus pokrývají použití na webu i v telefonii
- Konfiguraci můžeš změnit uprostřed relace bez přerušení připojení