Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Määritä istunto komennolla session.update

Oppitunti 3 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Määritä ääniagenttisi
  2. session.update:n täydellinen rakenne
  3. Asetukset yksityiskohtaisesti
  4. Istunnon päivittäminen keskellä keskustelua
  5. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Speech to Speech - ja Text to Speech -sivujen perusteella: 28 sisäänrakennettua ääntä, ja turn_detection määritetään pelkällä type-arvolla (valinnainen idle_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.update on ensimmäinen lähetettävä viesti session.created-tapahtuman jälkeen
  • instructions-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