Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Ovládanie udalostí WebSocket

Lekcia 4 z 14 Aktualizované 29. júla 2026 Mierne pokročilý
Na tejto strane
  1. Konverzácia zložená z JSON udalostí
  2. Čo tvoja aplikácia odosiela
  3. Čo vracia server
  4. Kostra klienta
  5. Záludná časť: prerušenia
  6. Kľúčové poznatky

Konverzácia zložená z JSON udalostí

Pod kapotou je hlasová výmena s Voice Agentom len prúdom JSON správ tečúcich oboma smermi cez WebSocket spojenie. Každá správa má pole type, ktoré hovorí, o čo ide. Kým nepoznáš túto slovnú zásobu, tvoj klient funguje len šťastnou náhodou. Akonáhle ju poznáš, presne vieš, kde zasiahnuť, aby si prerušil odpoveď, zobrazil prepis alebo sa zotavil z chyby.

Udalosti sa delia do dvoch skupín podľa smeru, ktorým putujú. Tie, ktoré odosielaš, riadia reláciu; tie, ktoré prijímaš, ti hovoria, čo sa deje na serveri.

Čo tvoja aplikácia odosiela

Tvoje odchádzajúce správy pokrývajú štyri potreby: konfiguráciu relácie, plnenie audio buffra, správu histórie konverzácie a riadenie generovania odpovedí.

UdalosťÚčel
session.updateKonfiguruje alebo rekonfiguruje reláciu (hlas, inštrukcie, nástroje, VAD, audio formát)
input_audio_buffer.appendOdosiela chunk audia zakódovaný v base64, nepretržite počas hovoru používateľa
input_audio_buffer.commitPotvrdí aktuálny obsah buffra ako správu používateľa; potrebné len v manuálnom režime
input_audio_buffer.clearVyprázdni audio buffer bez jeho spracovania
conversation.item.createPridá položku do konverzácie: textovú správu, staršiu históriu alebo výsledok volania funkcie
conversation.item.deleteVymaže položku konverzácie podľa jej ID
response.createPožiada model o vygenerovanie odpovede; automatické v režime VAD, explicitné v manuálnom režime
response.cancelZruší práve generovanú odpoveď

Dve z týchto správ si zaslúžia bližší pohľad. conversation.item.create je spôsob, akým vstrekneš kontext: používaš ho na obnovenie histórie skoršieho hovoru na začiatku novej relácie. Čo sa týka input_audio_buffer.clear, hodí sa, keď používateľ zjavne nepovedal nič hodné spracovania (napríklad odkašlanie zachytené príliš citlivým mikrofónom) a ty chceš radšej začať znova s čistým buffrom, než nechať model interpretovať šum.

Čo vracia server

Prichádzajúci prúd je rušnejší, pretože poskytuje neustály komentár ku každému kroku spracovania.

UdalosťVýznam
session.createdRelácia je otvorená
session.updatedAktualizácia konfigurácie bola aplikovaná
conversation.createdKonverzácia je nastavená
input_audio_buffer.speech_startedVAD zistí, že používateľ začal hovoriť
input_audio_buffer.speech_stoppedVAD zistí, že používateľ prestal hovoriť
input_audio_buffer.committedAudio buffer bol potvrdený, či už cez VAD alebo manuálne
response.createdGeneruje sa odpoveď
response.output_audio.deltaChunk odpovede v audio forme, v base64
response.output_audio.doneAudio odpoveď je kompletná
response.output_audio_transcript.deltaTextový prepis audia, streamovaný
response.doneOdpoveď je úplne dokončená
conversation.item.input_audio_transcription.completedPrepis správy používateľa je k dispozícii
response.text.deltaStreamovaný text pre nehlasové odpovede
response.function_call_arguments.deltaArgumenty volania funkcie, streamované
response.function_call_arguments.doneVolanie funkcie je kompletné a pripravené na spustenie
errorVyskytla sa chyba; väčšina chýb je obnoviteľná

Tá posledná si vyžaduje upozornenie. Prijatie error neznamená, že relácia je stratená. Podľa referencie xAI je väčšina chýb obnoviteľná a relácia zostáva otvorená, takže klient, ktorý uzavrie spojenie pri prvej chybe error, preruší konverzáciu, ktorá mohla pokračovať. Zaznamenaj ju, informuj používateľa, ak je to potrebné, ale socket nechaj otvorený.

Kostra klienta

V praxi sa všetko redukuje na switch podľa msg.type. Tu je minimálna podoba JavaScript klienta:

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

  switch (msg.type) {
    case "session.created":
      // Odoslať session.update s konfiguráciou
      break;

    case "input_audio_buffer.speech_started":
      // Používateľ hovorí: zastaviť prehrávanie audio odpovede
      break;

    case "response.output_audio.delta":
      // Dekódovať base64 a prehrať audio
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Spustiť funkciu a poslať späť výsledok
      handleFunctionCall(msg);
      break;

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

Štyri vetvy stačia na prevádzkovanie agenta: nakonfigurovať pri otvorení relácie, reagovať, keď používateľ začne hovoriť, prehrať prichádzajúce audio a spustiť funkcie. Ostatné udalosti obohacujú rozhranie a môžu počkať na druhú iteráciu.

Záludná časť: prerušenia

Barge-in, keď používateľ začne hovoriť, zatiaľ čo agent ešte odpovedá, je miestom, kde sa prejaví nedbalá implementácia. Server sám zruší aktuálnu odpoveď a začne generovať novú na základe toho, čo práve počul. Ale kým server prestal vysielať, tvoja aplikácia stále drží niekoľko sekúnd už prijatého audia vo svojom výstupnom buffri.

Ak neurobíš nič, používateľ bude stále počuť vetu, ktorú práve prerušil, zatiaľ čo do nej hovorí, a agent bude pôsobiť, ako keby nepočúval. Preto hneď, ako prijmeš speech_started, zastav prehrávanie audia, vyprázdni výstupný buffer, aby si neprehral zastaraný zvuk, a nechaj server spracovať nový vstup. Tieto dva kroky zaberie pár riadkov kódu a robia celý rozdiel medzi agentom, ktorého môžeš prerušiť, a tým, ktorý hovorí do prázdna.

Kľúčové poznatky

  • Klientske udalosti pokrývajú konfiguráciu, odosielanie audia, správu konverzácie a riadenie odpovedí
  • Serverové udalosti hlásia detekciu reči, audio chunky, prepisy a volania funkcií
  • VAD automaticky rieši prerušenia (barge-in)
  • Väčšina udalostí error je obnoviteľná: neuzatváraj spojenie, chybu ošetri
  • V manuálnom režime musíš explicitne zavolať commit a následne response.create