Määritä istunto komennolla session.update
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Speech to Speech - ja Text to Speech -sivujen perusteella: 28 sisäänrakennettua ääntä, ja
turn_detectionmääritetään pelkällätype-arvolla (valinnainenidle_timeout_ms). Lähteet: Speech to Speech · Text to Speech.
Määritä ääniagenttisi
Kun WebSocket-yhteys on avattu ja olet vastaanottanut session.created-tapahtuman, määritä istunto lähettämällä session.update-viesti. Tässä määritellään ääniagenttisi toiminta: sen persoonallisuus, ääni, käytettävissä olevat työkalut ja vuoronhavaintotapa.
session.update:n täydellinen rakenne
Tässä on yksityiskohtainen määritysesimerkki:
{
"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}
}
}
}
}
Asetukset yksityiskohtaisesti
Ohjeet (järjestelmäkehote)
instructions-kenttä vastaa teksti-APIen järjestelmäkehottetta: se määrittelee ääniagenttisi persoonallisuuden, kontekstin ja rajoitukset. Kirjoittamiseen liittyy kuitenkin äänelle ominainen rajoite: lyhyys. Jokainen kehotteen tokeni käsitellään ennen ensimmäistä vastausta, ja liian laaja kehote aiheuttaa huomattavaa viivettä heti puhelun yhdistyessä. Pysy olennaisissa asioissa ja siirrä yksityiskohdat sovelluslogiikkaasi. Tässä tiukassa budjetissa kolme asiaa ansaitsee paikkansa. Sävy (muodollinen, ystävällinen, tekninen), sillä ääniagentti edustaa brändiäsi kirjaimellisesti asiakkaan korvassa. Kieli: määritä se (”vastaa englanniksi”), muuten agentti saattaa seurata käyttäjän kieltä tai kysymyksen kieltä. Ja rajat: mitä agentti voi tehdä ja ennen kaikkea mitä sen on kieltäydyttävä tekemästä tai ohjattava ihmiselle, sillä puhelimessa aiheen ulkopuolinen vastaus ehtii ulos ennen kuin kukaan ehtii tarkistaa sitä.
Ääni
voice-asetus hyväksyy yhden xAI:n 28:sta sisäänrakennetusta äänestä (tilanne 3. marraskuuta 2026), joita käyttävät sekä ääniagentti että tekstistä puheeksi -toiminto, tai Custom Voices API:lla luodun mukautetun äänen tunnisteen. Äänitunnisteet eivät ole kirjainkokoherkkiä: eve, Eve ja EVE viittaavat kaikki samaan ääneen. Jokainen ääni puhuu kaikkia tuettuja kieliä.
Viisi alkuperäistä ääntä xAI:n kuvailemina:
- eve: energinen ja iloinen, brittiaksentti
- ara: lämmin ja ystävällinen
- rex: itsevarma ja selkeä
- sal: sujuva ja tasapainoinen
- leo: auktoriteettinen ja voimakas, brittiaksentti
Niiden lisäksi on 23 uudempaa ääntä: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora ja liora. Saat ajantasaisen listan, jossa on kunkin äänen sävy ja käyttötarkoitukset, komennolla GET /v1/tts/voices tai xAI:n Text to Speech -sivulta.
Työkalut
tools-taulukko määrittelee työkalut, joita agentti voi kutsua keskustelun aikana. Voit yhdistää useita tyyppejä: verkkohaku, X-haku, mukautetut funktiot, RAG-kokoelmat ja MCP-palvelimet. Seuraavat oppitunnit käsittelevät työkaluja yksityiskohtaisesti.
Äänimääritykset
audio-objekti asettaa syöte- ja tulostemuodot. Voit käyttää eri muotoja syötteelle ja tulosteelle, jos arkkitehtuurisi niin vaatii (esimerkiksi G.711-vastaanotto puhelinjärjestelmästä ja PCM-lähetys selaimeen).
Istunnon päivittäminen keskellä keskustelua
Voit lähettää session.update-komennon useita kertoja keskustelun aikana. Tämä mahdollistaa agentin toiminnan muuttamisen lennossa:
// Vaihda ääni keskellä keskustelua
ws.send(JSON.stringify({
type: "session.update",
session: {
voice: "Ara"
}
}));
// Lisää toinen työkalu
ws.send(JSON.stringify({
type: "session.update",
session: {
tools: [
{ type: "web_search" },
{ type: "x_search" }
]
}
}));
xAI:n dokumentaatio tukee nimenomaisesti istunnon aikaisia muutoksia useille asetuksille (transkriptiokieli, avainsanat, ääntämisen korvaukset, audiokuljetus), ja session.updated vahvistaa ne: tarkista se varmistaaksesi sovelletun määrityksen.
Keskeiset asiat
session.updateon ensimmäinen lähetettävä viestisession.created-tapahtuman jälkeeninstructions-kenttä määrittelee agentin persoonallisuuden ja rajoitukset- Käytettävissä on 28 sisäänrakennettua ääntä (mukaan lukien eve, ara, rex, sal ja leo) sekä mukautetut äänet
- Äänimääritykset ja työkalut ovat muokattavissa
- Voit lähettää
session.update-komennon useita kertoja muuttaaksesi toimintaa keskellä keskustelua