Konfiguracja sesji za pomocą session.update
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie stron xAI Speech to Speech oraz Text to Speech: 28 wbudowanych głosów, a parametr
turn_detectionustawiany jest wyłącznie przez jego poletype(z opcjonalnymidle_timeout_ms). Źródła: Speech to Speech · Text to Speech.
Skonfiguruj swojego agenta głosowego
Gdy połączenie WebSocket zostanie nawiązane i otrzymasz zdarzenie session.created, skonfiguruj sesję, wysyłając wiadomość session.update. To tutaj definiujesz zachowanie swojego agenta głosowego: jego osobowość, głos, narzędzia, z których może korzystać, oraz sposób wykrywania zmian mówcy (turn detection).
Pełna struktura session.update
Oto szczegółowy przykład konfiguracji:
{
"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}
}
}
}
}
Szczegółowy opis ustawień
Instrukcje (monit systemowy)
Pole instructions odpowiada monitowi systemowemu (system prompt) w interfejsach API tekstowych: definiuje osobowość, kontekst i ograniczenia Twojego agenta głosowego. Pisanie go wiąże się jednak z ograniczeniem specyficznym dla głosu: zwięzłością. Każdy token monitu jest przetwarzany przed pierwszą odpowiedzią, a rozwlekły prompt powoduje zauważalne opóźnienia w momencie nawiązania połączenia. Trzymaj się essentials i przenoś szczegóły do logiki swojej aplikacji. W ramach tego ścisłego budżetu trzy elementy zasługują na uwagę. Ton (formalny, przyjazny, techniczny), ponieważ agent głosowy dosłownie uosabia Twoją markę w uchu klienta. Język: określ go („odpowiadaj po angielsku“), inaczej agent może podążać za językiem użytkownika lub pytaniem. I limity: co agent może zrobić, a przede wszystkim czego musi odmówić lub przekazać człowiekowi, ponieważ w rozmowie telefonicznej odpowiedź wykraczająca poza zakres zostaje wypowiedziana, zanim ktokolwiek zdąży ją zweryfikować.
Głos
Ustawienie voice akceptuje jeden z 28 wbudowanych głosów xAI (stan na 3 listopada 2026 r.), współdzielonych przez agenta głosowego i syntezę mowy (text-to-speech), lub identyfikator głosu niestandardowego utworzonego za pomocą interfejsu API Custom Voices. Identyfikatory głosów nie rozróżniają wielkości liter: eve, Eve i EVE odnoszą się do tego samego głosu. Każdy głos obsługuje każdy obsługiwany język.
Pięć oryginalnych głosów, zgodnie z opisem xAI:
- eve: energiczny i radosny, brytyjski akcent
- ara: ciepły i przyjazny
- rex: pewny siebie i wyraźny
- sal: gładki i zrównoważony
- leo: autorytatywny i potężny, brytyjski akcent
Dołącza do nich dwadzieścia trzy nowsze głosy: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora oraz liora. Aktualną listę, wraz z tonem i przypadkami użycia dla każdego głosu, możesz uzyskać poprzez wywołanie GET /v1/tts/voices lub na stronie xAI Text to Speech.
Narzędzia
Tablica tools definiuje narzędzia, które agent może wywołać podczas rozmowy. Możesz łączyć różne typy: wyszukiwanie w sieci, wyszukiwanie w X, funkcje niestandardowe, kolekcje RAG i serwery MCP. Kolejne lekcje szczegółowo omawiają narzędzia.
Konfiguracja audio
Obiekt audio ustawia formaty wejścia i wyjścia. Możesz użyć różnych formatów dla wejścia i wyjścia, jeśli wymaga tego Twoja architektura (na przykład odbieranie G.711 z systemu telefonicznego i wysyłanie PCM do przeglądarki).
Aktualizacja sesji w trakcie rozmowy
Możesz wysyłać session.update wielokrotnie w trakcie rozmowy. Pozwala to na zmianę zachowania agenta w locie:
// Zmień głos w trakcie rozmowy
ws.send(JSON.stringify({
type: "session.update",
session: {
voice: "Ara"
}
}));
// Dodaj kolejne narzędzie
ws.send(JSON.stringify({
type: "session.update",
session: {
tools: [
{ type: "web_search" },
{ type: "x_search" }
]
}
}));
Dokumentacja xAI wyraźnie obsługuje zmiany w trakcie sesji dla kilku ustawień (język transkrypcji, słowa kluczowe, zamiany wymowy, transport audio), a zdarzenie session.updated potwierdza ich zastosowanie: sprawdź je, aby potwierdzić użytą konfigurację.
Kluczowe wnioski
session.updateto pierwsza wiadomość do wysłania po otrzymaniusession.created- Pole
instructionsdefiniuje osobowość i ograniczenia agenta - Dostępnych jest 28 wbudowanych głosów (w tym eve, ara, rex, sal i leo) oraz głosy niestandardowe
- Konfiguracja audio i narzędzia są konfigurowalne
- Możesz wysyłać
session.updatewielokrotnie, aby zmienić zachowanie w trakcie rozmowy