Udalosti zo servera na klienta
Na tejto strane
Správy, ktoré dostávaš
Server ti posiela množstvo udalostí, aby ťa informoval o stave konverzácie, doručil zvukovú odpoveď a nahlásil chyby. Pochopenie týchto udalostí je kľúčové pre vytvorenie responzívnej a spoľahlivej aplikácie.
Udalosti relácie a konverzácie
Tieto udalosti prichádzajú pri nadviazaní spojenia a po každej zmene konfigurácie:
session.created: relácia je otvorená; udalosť obsahuje konfiguráciu reláciesession.updated: konfigurácia bola úspešne aktualizovanáconversation.created: kanál konverzácie je nastavený
Udalosti zvukovej vyrovnávacej pamäte
Tieto udalosti ťa informujú o hlasovej aktivite, ktorú zistí detekcia hlasu (VAD):
input_audio_buffer.speech_started: VAD zistilo, že používateľ začal hovoriťinput_audio_buffer.speech_stopped: VAD zistilo koniec rečiinput_audio_buffer.committed: zvuková vyrovnávacia pamäť bola potvrdená ako správa
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// Používateľ hovorí: zobraz vizuálny indikátor
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// Používateľ skončil: skry indikátor
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Zvuková správa sa spracováva
showProcessingIndicator(true);
break;
}
});
Udalosti zvukovej odpovede
Zvuk odpovede sa prenáša prostredníctvom dvoch udalostí.
response.output_audio.delta
Každá delta obsahuje časť zvuku zakódovanú v base64. Zhromaždi ich a prehrať v správnom poradí:
{
"type": "response.output_audio.delta",
"delta": "SGVsbG8gV29ybGQ...",
"item_id": "item_resp_001",
"output_index": 0,
"content_index": 0
}
case "response.output_audio.delta":
const audioChunk = base64ToArrayBuffer(event.delta);
audioPlayer.enqueue(audioChunk);
break;
response.output_audio.done
Signalizuje, že bol odoslaný celý zvuk odpovede:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Udalosti prepisu
API dokáže prepísať zvuk používateľa aj zvuk odpovede:
conversation.item.input_audio_transcription.completed: prepis toho, čo používateľ povedalresponse.output_audio_transcript.delta: streamovaný prepis odpovede agenta
case "conversation.item.input_audio_transcription.completed":
console.log("Používateľ povedal:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Textové udalosti
Ak agent generuje text (navyše alebo namiesto zvuku), dostaneš:
response.text.delta: streamovaný fragment textu
{
"type": "response.text.delta",
"delta": "Vaša objednávka bola"
}
Udalosti volania funkcií
Keď sa agent rozhodne zavolať funkciu, emitujú sa dve udalosti:
response.function_call_arguments.delta: argumenty funkcie, streamovanéresponse.function_call_arguments.done: úplné volanie funkcie so všetkými jej argumentmi
Lekcia 13 o hlasovom volaní funkcií sa týmito udalosťami zaoberá podrobnejšie.
response.done
Táto udalosť označuje úplný koniec odpovede. Obsahuje zhrnutie odpovede vrátane štatistík využitia:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Udalosť chyby
Táto udalosť hlási chyby. Podľa referencie xAI je väčšina chýb obnoviteľná a spojenie WebSocket zostáva otvorené:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Zadaný neplatný formát zvuku"
}
}
Tvoja aplikácia by mala tieto chyby zaznamenávať a v závislosti od ich závažnosti zobraziť používateľovi správu alebo sa pokúsiť problém automaticky opraviť.
Kľúčové poznatky
- Server posiela udalosti pre každý krok: detekciu hlasu, zvuk, prepis, text a chyby
- Zvuková odpoveď prichádza ako časti v base64 prostredníctvom
response.output_audio.delta - Prepisy sú dostupné pre vstup používateľa aj výstup agenta
response.doneoznačuje koniec úplnej odpovede- Väčšina chýb nahlásených prostredníctvom udalosti
errorje obnoviteľná: spojenie zostáva otvorené