Ovládanie udalostí WebSocket
Na tejto strane
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.update | Konfiguruje alebo rekonfiguruje reláciu (hlas, inštrukcie, nástroje, VAD, audio formát) |
input_audio_buffer.append | Odosiela chunk audia zakódovaný v base64, nepretržite počas hovoru používateľa |
input_audio_buffer.commit | Potvrdí aktuálny obsah buffra ako správu používateľa; potrebné len v manuálnom režime |
input_audio_buffer.clear | Vyprázdni audio buffer bez jeho spracovania |
conversation.item.create | Pridá položku do konverzácie: textovú správu, staršiu históriu alebo výsledok volania funkcie |
conversation.item.delete | Vymaže položku konverzácie podľa jej ID |
response.create | Požiada model o vygenerovanie odpovede; automatické v režime VAD, explicitné v manuálnom režime |
response.cancel | Zruší 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.created | Relácia je otvorená |
session.updated | Aktualizácia konfigurácie bola aplikovaná |
conversation.created | Konverzácia je nastavená |
input_audio_buffer.speech_started | VAD zistí, že používateľ začal hovoriť |
input_audio_buffer.speech_stopped | VAD zistí, že používateľ prestal hovoriť |
input_audio_buffer.committed | Audio buffer bol potvrdený, či už cez VAD alebo manuálne |
response.created | Generuje sa odpoveď |
response.output_audio.delta | Chunk odpovede v audio forme, v base64 |
response.output_audio.done | Audio odpoveď je kompletná |
response.output_audio_transcript.delta | Textový prepis audia, streamovaný |
response.done | Odpoveď je úplne dokončená |
conversation.item.input_audio_transcription.completed | Prepis správy používateľa je k dispozícii |
response.text.delta | Streamovaný text pre nehlasové odpovede |
response.function_call_arguments.delta | Argumenty volania funkcie, streamované |
response.function_call_arguments.done | Volanie funkcie je kompletné a pripravené na spustenie |
error | Vyskytla 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í
errorje obnoviteľná: neuzatváraj spojenie, chybu ošetri - V manuálnom režime musíš explicitne zavolať
commita následneresponse.create