Konfiguriranje glasovne sesije
Na ovoj stranici
Ažurirano 3. studenoga 2026., na temelju xAI stranice Speech to Speech i vodiča za glasovno poticanje. Izvori: Speech to Speech · Prompting Guide.
Poruka koja sve pokreće: session.update
Čim se WebSocket veza uspostavi, još se ništa ne događa. Poruka session.update je ono što agentu daje karakter: glas koji koristi, upute kojima se vodi, način na koji detektira izmjenu govornika i koje alate smije pozvati. Zamisli to kao rodni list sesije. Sve ostalo u razgovoru proizlazi iz nje.
{
"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" }
]
}
}
Poslužitelj to potvrđuje događajem session.updated. Ovu poruku ne moraš poslati samo jednom. Možeš je poslati ponovno usred razgovora kako bi dinamički promijenio postavku, primjerice za prelazak s jednog glasa na drugi kada poziv prijeđe s prodaje na tehničku podršku, a da pritom nikada ne prekineš vezu.
Piši upute za uho, a ne za oko
Polje instructions igra ulogu sistemske poruke (system prompt). Iskoristi ga za definiranje osobnosti agenta (formalna, opuštena, tehnička), tema koje smije obrađivati, ograničenja njegovih odgovora (duljina, format, jezik) te poslovnog konteksta koji mu je potreban: ime tvoje tvrtke, asortiman proizvoda i interni postupci.
Kvaka je u tome što ono što čini dobar pisani prompt često stvara lošeg glasovnog agenta. Prepušten sam sebi, model piše odgovore od deset redaka. Naglas pročitani, oni se otežu i korisnik izgubi pažnju prije kraja. Zato izričito traži kratke i izravne odgovore. Ako tvoja aplikacija radi na jednom jeziku, navedi koji, inače bi agent mogao prijeći na jezik koji odgovara naglasu sugovornika. Također, reci mu što da radi kada ne razumije: uputa poput „postavi razjašnjavajuće pitanje umjesto nagađanja“ sprječava da pogrešno čujan broj narudžbe pokrene besmislenu pretragu. xAI vodič za glasovno poticanje čak predlaže strukturu od pet dijelova (uloga i persona, cilj, tijek razgovora, zaštitne mjere i eskalacija, stil glasa) te preporučuje jednu ili dvije kratke rečenice po izmjeni govornika, osim ako pozivatelj ne zatraži više detalja.
Detekcija izmjene govornika
Blok turn_detection odlučuje tko govori i kada, a xAI dokumentacija nudi samo dvije postavke za njega. Prva je type. U načinu rada "server_vad", poslužitelj samostalno detektira kraj svake izjave, potvrđuje audio, pokreće odgovor i rukuje prekidima: sve što ti trebaš učiniti jest slati audio putem input_audio_buffer.append. Druga postavka, idle_timeout_ms, nije obavezna. Ako korisnik ostane tiho toliko milisekundi nakon odgovora, poslužitelj će ga potaknuti na govor, i ponoviti to nakon svake nove tišine iste duljine.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Ne postoji prag osjetljivosti niti trajanje tišine koje možeš podesiti. Parametri threshold, silence_duration_ms i prefix_padding_ms koje ćeš vidjeti u primjerima napisanima za OpenAI Realtime API ne pojavljuju se u xAI dokumentaciji.
Ako ti automatsko ponašanje ne odgovara, postavi tip na null i preuzmi kontrolu. Tada je na tebi da međuspremnički pohraniš audio s input_audio_buffer.append, izričito potvrdiš izmjenu govornika s input_audio_buffer.commit i pokreneš generiranje s response.create. Ručni način pravi je izbor za sučelje tipa „pritisni za govor“ (push-to-talk) ili kad god želiš preciznu kontrolu nad trenutkom kada agent progovori.
Odaberi ispravan audio format
Blok audio neovisno postavlja ulazne i izlazne formate:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Prihvaćene su četiri vrste. Ako ne navedeš nijednu, dobit ćeš PCM na 24.000 Hz:
| Vrsta | Kodiranje | Frekvencije uzorkovanja |
|---|---|---|
audio/pcm | PCM Linear16, little-endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (sjevernoamerička telefonija) | Samo 8000 Hz |
audio/pcma | G.711 A-law (europska telefonija) | Samo 8000 Hz |
audio/opus | Opus, jedan paket po poruci | 24000 Hz |
Tvoj kanal isporuke diktira izbor. Web aplikacija u pregledniku dobro funkcionira s PCM-om na 24.000 Hz, što je dobra ravnoteža između percipirane kvalitete i propusnosti. Integracija sa SIP telefonom nema izbora: mreža prenosi G.711 na 8.000 Hz, a forsiranje formata više kvalitete na njega samo dodaje besmislenu konverziju.
Daj agentu alate
Niz tools nabraja što agent smije pozvati tijekom razgovora, a u istoj sesiji možeš miješati različite vrste:
{
"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"]
}
}
]
}
Ti osiguravaš alatnicu; agent bira alat. Kako razgovor teče, on odlučuje da pitanje o vijestima zahtijeva web pretragu, dok broj narudžbe zahtijeva get_order_status. Tvoj posao je dakle manje orchestriranje poziva, a više jasno opisivanje svakog alata kako bi agent donio ispravnu odluku.
Ključne točke
- Poruka
session.updatekonfigurira glas, upute, VAD i alate - VAD na strani poslužitelja (
server_vad) detektira izmjene govornika i rukuje prekidima;idle_timeout_msje jedina postavka - Ručni način (
turn_detection.typepostavljen nanull) daje ti preciznu kontrolu, primjerice kod „pritisni za govor“ - Audio formati PCM, G.711 i Opus pokrivaju slučajeve uporabe i za web i za telefoniju
- Konfiguraciju možeš promijeniti usred sesije bez prekidanja veze