Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Ovládněte události WebSocket

Lekce 4 z 14 Aktualizováno 29. července 2026 Mírně pokročilý
Na této stránce
  1. Konverzace složená z JSON událostí
  2. Co vaše aplikace odesílá
  3. Co server posílá zpět
  4. Kostra klienta
  5. Ošemetná část: přerušování
  6. Klíčové poznatky

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.updateKonfiguruje nebo rekonfiguruje relaci (hlas, instrukce, nástroje, VAD, formát audia)
input_audio_buffer.appendOdesílá chunk audia zakódovaný v base64, průběžně zatímco uživatel mluví
input_audio_buffer.commitPotvrdí aktuální obsah bufferu jako zprávu uživatele; potřebné pouze v manuálním režimu
input_audio_buffer.clearVyprázdní audio buffer bez jeho zpracování
conversation.item.createPřidá položku do konverzace: textovou zprávu, dřívější historii nebo výsledek volání funkce
conversation.item.deleteSmaže položku konverzace podle jejího ID
response.createPožádá model o vygenerování odpovědi; automatické v režimu VAD, explicitní v manuálním režimu
response.cancelZruší 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álostVýznam
session.createdRelace je otevřena
session.updatedByla aplikována aktualizace konfigurace
conversation.createdKonverzace je nastavena
input_audio_buffer.speech_startedVAD detekuje, že uživatel začal mluvit
input_audio_buffer.speech_stoppedVAD detekuje, že uživatel přestal mluvit
input_audio_buffer.committedAudio buffer byl potvrzen, buď pomocí VAD, nebo manuálně
response.createdOdpověď se generuje
response.output_audio.deltaChunk odpovědního audia, v base64
response.output_audio.doneOdpovědní audio je kompletní
response.output_audio_transcript.deltaTextový přepis audia, streamován
response.doneOdpověď je zcela dokončena
conversation.item.input_audio_transcription.completedPřepis zprávy uživatele je k dispozici
response.text.deltaStreamovaný text pro nehlasové odpovědi
response.function_call_arguments.deltaArgumenty volání funkce, streamovány
response.function_call_arguments.doneVolání funkce je kompletní a připraveno ke spuštění
errorDoš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í error je obnovitelná: nezavírejte připojení, chybu ošetřete
  • V manuálním režimu musíte explicitně volat commit a následně response.create