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

WebSocket-tapahtumien hallinta

Oppitunti 4 / 14 Päivitetty 29. heinäkuuta 2026 Keskitasoinen
Tällä sivulla
  1. JSON-tapahtumista koostuva keskustelu
  2. Mitä sovelluksesi lähettää
  3. Mitä palvelin lähettää takaisin
  4. Asiakasohjelman runko
  5. Haastava kohta: keskeytykset
  6. Keskeiset asiat

JSON-tapahtumista koostuva keskustelu

Konepellin alla äänikeskustelu Voice Agentin kanssa on pelkkä JSON-viestien virta, joka kulkee molempiin suuntiin WebSocket-yhteyden yli. Jokaisessa viestissä on type-kenttä, joka kertoo viestin luonteen. Ilman tätä sanastoa asiakasohjelmasi toimii onnenkaupalla. Kun hallitset sen, tiedät tarkasti, missä vaiheessa puuttua asiaan keskeyttääksesi vastauksen, näyttääksesi litteroinnin tai palautuaksesi virhetilanteesta.

Tapahtumat jakautuvat kahteen perheeseen suunnan perusteella. Lähettämäsi viestit ohjaavat istuntoa; vastaanottamasi viestit kertovat, mitä palvelimella tapahtuu.

Mitä sovelluksesi lähettää

Lähtevät viestisi kattavat neljä tarvetta: istunnon määrittämisen, äänipuskurin syöttämisen, keskusteluhistorian hallinnan ja vastauksen generoinnin ohjaamisen.

TapahtumaTarkoitus
session.updateMäärittää tai uudelleenmäärittää istunnon (ääni, ohjeet, työkalut, VAD, äänimuoto)
input_audio_buffer.appendLähettää base64-koodatun äänipalan jatkuvasti käyttäjän puhuessa
input_audio_buffer.commitVahvistaa puskurin nykyisen sisällön käyttäjän viestinä; tarvitaan vain manuaalitilassa
input_audio_buffer.clearTyhjentää äänipuskurin käsittelemättä sitä
conversation.item.createLisää kohteen keskusteluun: tekstiviestin, aiemman historian tai funktiokutsun tuloksen
conversation.item.deletePoistaa keskustelukohteen sen ID:n perusteella
response.createPyytää mallia generoimaan vastauksen; automaattinen VAD-tilassa, eksplisiittinen manuaalitilassa
response.cancelPeruuttaa generoitavan vastauksen

Kaksi näistä viesteistä ansaitsee tarkemman tarkastelun. conversation.item.create on tapa syöttää kontekstia: sen avulla palautat aiemman puhelun historian uuden istunnon alussa. input_audio_buffer.clear puolestaan on hyödyllinen, kun käyttäjä ei selvästi sanonut mitään käsittelemisen arvoista (esim. liian herkän mikrofonin sieppaama kurkun selvittely), ja haluat mieluummin aloittaa puhtaalta pöydältä kuin antaa mallin tulkita kohinaa.

Mitä palvelin lähettää takaisin

Saapuva virta on vilkkaampi, koska se tarjoaa reaaliaikaista kommentointia jokaisesta käsittelyvaiheesta.

TapahtumaMerkitys
session.createdIstunto on avattu
session.updatedKokoonpanopäivitys on otettu käyttöön
conversation.createdKeskustelu on asetettu
input_audio_buffer.speech_startedVAD havaitsee käyttäjän alkaneen puhua
input_audio_buffer.speech_stoppedVAD havaitsee käyttäjän lopettaneen puhumisen
input_audio_buffer.committedÄänipuskuri on vahvistettu (VAD:n tai manuaalisesti)
response.createdVastausta generoidaan
response.output_audio.deltaPala vastausääntä base64-muodossa
response.output_audio.doneVastausääni on valmis
response.output_audio_transcript.deltaÄänen tekstilitterointi suoratoistona
response.doneVastaus on täysin päättynyt
conversation.item.input_audio_transcription.completedKäyttäjän viestin litterointi on saatavilla
response.text.deltaSuoratoistettu teksti ei-äänivastauksille
response.function_call_arguments.deltaFunktiokutsun argumentit suoratoistona
response.function_call_arguments.doneFunktiokutsu on valmis ja odottaa suorittamista
errorTapahtui virhe; useimmat virheet ovat korjattavissa

Viimeinen kohta vaatii varoituksen. error-tapahtuman vastaanottaminen ei tarkoita istunnon menettämistä. xAI:n referenssin mukaan useimmat virheet ovat korjattavissa ja istunto pysyy auki, joten asiakasohjelma, joka sulkee yhteyden ensimmäisestä error-tapahtumasta, katkaisee keskustelun, joka olisi voinut jatkua. Kirjaa virhe, ilmoita siitä käyttäjälle tarvittaessa, mutta pidä socket auki.

Asiakasohjelman runko

Käytännössä kaikki tiivistyy kytkentään msg.type:n perusteella. Tässä on JavaScript-asiakasohjelman minimaalinen rakenne:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // Lähetä session.update kokoonpanolla
      break;

    case "input_audio_buffer.speech_started":
      // Käyttäjä puhuu: pysäytä toistettava vastausääni
      break;

    case "response.output_audio.delta":
      // Pura base64 ja toista ääni
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Suorita funktio ja lähetä tulos takaisin
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Voice Agent -virhe:", msg.error);
      break;
  }
};

Neljä haaraa riittää agentin pyörittämiseen: määritä istunnon avautuessa, reagoi käyttäjän puhumaan alkaessa, toista saapuva ääni ja suorita funktiot. Muut tapahtumat rikastuttavat käyttöliittymää ja voivat odottaa toista iterointia.

Haastava kohta: keskeytykset

Barge-in, eli tilanne jossa käyttäjä alkaa puhua agentin vielä vastatessa, on kohta jossa huolimaton toteutus paljastuu. Palvelin peruuttaa nykyisen vastauksen itsestään ja alkaa generoida uutta kuulemansa perusteella. Mutta vaikka palvelin on lopettanut lähettämisen, sovelluksellasi on edelleen useita sekunteja jo vastaanotettua ääntä lähtöpuskurissaan.

Jos et tee mitään, käyttäjä kuulee edelleen lausetta, jonka hän juuri keskeytti, puhuen sen päälle, ja agentti vaikuttaa siltä ettei se kuuntele. Siksi heti kun vastaanotat speech_started-tapahtuman, pysäytä toistettava ääni, tyhjennä lähtöpuskuri vanhentuneen äänen soittamisen estämiseksi ja anna palvelimen käsitellä uusi syöte. Nämä kaksi vaihetta vievät vain muutaman rivin koodia, mutta tekevät eron agentin, jonka voi keskeyttää, ja agentin, joka puhuu tyhjiin.

Keskeiset asiat

  • Asiakastapahtumat kattavat kokoonpanon, äänen lähettämisen, keskustelun hallinnan ja vastausten ohjaamisen
  • Palvelintapahtumat raportoivat puheen havaitsemisesta, äänipaloista, litteroinneista ja funktiokutsuista
  • VAD hoitaa keskeytykset (barge-in) automaattisesti
  • Useimmat error-tapahtumat ovat korjattavissa: älä sulje yhteyttä, vaan käsittele virhe
  • Manuaalitilassa sinun on kutsuttava commit ja sen jälkeen response.create eksplisiittisesti