Ovládněte události WebSocket
Na této stránce
Konverzace složená z JSON událostí
Pod kapotou je hlasová výměna s Voice Agentem pouze proudem JSON zpráv proudících oběma směry přes WebSocket připojení. Každá zpráva má pole type, které říká, o co jde. Dokud neznáte tuto slovní zásobu, váš klient funguje jen díky náhodě. Jakmile ji znáte, přesně víte, kde zasáhnout, abyste přerušili odpověď, zobrazili přepis nebo se zotavili z chyby.
Události spadají do dvou rodin v závislosti na směru, kterým putují. Ty, které odesíláte, řídí relaci; ty, které přijímáte, vám sdělují, co se děje na serveru.
Co vaše aplikace odesílá
Vaše odchozí zprávy pokrývají čtyři potřeby: konfiguraci relace, krmení audio bufferu, správu historie konverzace a řízení generování odpovědí.
| Událost | Účel |
|---|---|
session.update | Konfiguruje nebo rekonfiguruje relaci (hlas, instrukce, nástroje, VAD, formát audia) |
input_audio_buffer.append | Odesílá chunk audia zakódovaný v base64, průběžně zatímco uživatel mluví |
input_audio_buffer.commit | Potvrdí aktuální obsah bufferu jako zprávu uživatele; potřebné pouze v manuálním režimu |
input_audio_buffer.clear | Vyprázdní audio buffer bez jeho zpracování |
conversation.item.create | Přidá položku do konverzace: textovou zprávu, dřívější historii nebo výsledek volání funkce |
conversation.item.delete | Smaže položku konverzace podle jejího ID |
response.create | Požádá model o vygenerování odpovědi; automatické v režimu VAD, explicitní v manuálním režimu |
response.cancel | Zruší odpověď, která se právě generuje |
Dvě z těchto zpráv si zaslouží bližší pohled. conversation.item.create je způsob, jak injektovat kontext: používáte jej k obnovení historie dřívějšího hovoru na začátku nové relace. Co se týče input_audio_buffer.clear, hodí se, když uživatel zjevně neřekl nic, co by stálo za zpracování (například odkašlání zachycené příliš citlivým mikrofonem), a vy raději začnete znovu s čistým bufferem, než abyste nechali model interpretovat šum.
Co server posílá zpět
Příchozí proud je rušnější, protože poskytuje průběžný komentář ke každému kroku zpracování.
| Událost | Význam |
|---|---|
session.created | Relace je otevřena |
session.updated | Byla aplikována aktualizace konfigurace |
conversation.created | Konverzace je nastavena |
input_audio_buffer.speech_started | VAD detekuje, že uživatel začal mluvit |
input_audio_buffer.speech_stopped | VAD detekuje, že uživatel přestal mluvit |
input_audio_buffer.committed | Audio buffer byl potvrzen, buď pomocí VAD, nebo manuálně |
response.created | Odpověď se generuje |
response.output_audio.delta | Chunk odpovědního audia, v base64 |
response.output_audio.done | Odpovědní audio je kompletní |
response.output_audio_transcript.delta | Textový přepis audia, streamován |
response.done | Odpověď je zcela dokončena |
conversation.item.input_audio_transcription.completed | Přepis zprávy uživatele je k dispozici |
response.text.delta | Streamovaný text pro nehlasové odpovědi |
response.function_call_arguments.delta | Argumenty volání funkce, streamovány |
response.function_call_arguments.done | Volání funkce je kompletní a připraveno ke spuštění |
error | Došlo k chybě; většina chyb je obnovitelná |
Ta poslední si zaslouží varování. Přijetí error neznamená, že je relace ztracena. Podle reference xAI je většina chyb obnovitelná a relace zůstává otevřená, takže klient, který při první chybě error uzavře připojení, rozbije konverzaci, která mohla pokračovat. Zaznamenejte ji, případně informujte uživatele, ale socket udržujte otevřený.
Kostra klienta
V praxi se vše redukuje na přepínač podle msg.type. Zde je minimální podoba klienta v JavaScriptu:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Odeslat session.update s konfigurací
break;
case "input_audio_buffer.speech_started":
// Uživatel mluví: zastavit přehrávání odpovědního audia
break;
case "response.output_audio.delta":
// Dekódovat base64 a přehrát audio
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Spustit funkci a poslat zpět výsledek
handleFunctionCall(msg);
break;
case "error":
console.error("Chyba Voice Agent:", msg.error);
break;
}
};
Čtyři větve stačí k provozování agenta: nakonfigurovat při otevření relace, reagovat, když uživatel začne mluvit, přehrávat příchozí audio a spouštět funkce. Ostatní události obohacují rozhraní a mohou počkat na druhou iteraci.
Ošemetná část: přerušování
Barge-in, kdy uživatel začne mluvit, zatímco agent stále odpovídá, je místem, kde se projeví nedbalá implementace. Server sám zruší aktuální odpověď a začne generovat novou na základě toho, co právě slyšel. Zatímco server přestal odesílat, vaše aplikace stále drží několik sekund již přijatého audia ve svém výstupním bufferu.
Pokud nic neuděláte, uživatel stále slyší větu, kterou právě přerušil, zatímco do ní mluví, a agent působí, jako by neposlouchal. Jakmile tedy obdržíte speech_started, zastavte přehrávání audia, vyprázdněte výstupní buffer, abyste nepřehrávali zastaralý zvuk, a nechte server zpracovat nový vstup. Tyto dva kroky zabere pár řádků kódu a dělají rozdíl mezi agentem, kterého můžete přerušit, a tím, který mluví do prázdna.
Klíčové poznatky
- Klientské události pokrývají konfiguraci, odesílání audia, správu konverzace a řízení odpovědí
- Serverové události hlásí detekci řeči, audio chunky, přepisy a volání funkcí
- VAD automaticky řeší přerušování (barge-in)
- Většina událostí
errorje obnovitelná: nezavírejte připojení, chybu ošetřete - V manuálním režimu musíte explicitně volat
commita následněresponse.create