Przejdź do głównej treści
Polski— Wybierz język
Menu

Opanuj zdarzenia WebSocket

Lekcja 4 z 14 Zaktualizowano 29 lipca 2026 Średnio zaawansowani
Na tej stronie
  1. Rozmowa złożona ze zdarzeń JSON
  2. Co wysyła Twoja aplikacja
  3. Co wysyła serwer
  4. Szkielet klienta
  5. Trudna część: przerwanie
  6. Kluczowe wnioski

Rozmowa złożona ze zdarzeń JSON

Pod maską wymiana głosowa z Voice Agent to po prostu strumień komunikatów JSON płynący w obie strony przez połączenie WebSocket. Każda wiadomość zawiera pole type, które określa jej rodzaj. Dopóki nie poznasz tego słownictwa, Twój klient działa na ślepo. Gdy już je opanujesz, będziesz wiedział dokładnie, gdzie介入ć, aby przerwać odpowiedź, wyświetlić transkrypcję lub odzyskać kontrolę po błędzie.

Zdarzenia dzielą się na dwie rodziny, w zależności od kierunku ich przesyłania. Te, które wysyłasz, sterują sesją; te, które otrzymujesz, informują Cię o tym, co dzieje się po stronie serwera.

Co wysyła Twoja aplikacja

Twoje wiadomości wychodzące obsługują cztery potrzeby: konfigurację sesji, dostarczanie bufora audio, zarządzanie historią rozmowy oraz kontrolowanie generowania odpowiedzi.

ZdarzenieCel
session.updateKonfiguruje lub rekonfiguruje sesję (głos, instrukcje, narzędzia, VAD, format audio)
input_audio_buffer.appendWysyła fragment audio zakodowany w base64, ciągle podczas mówienia użytkownika
input_audio_buffer.commitZatwierdza bieżącą zawartość bufora jako wiadomość użytkownika; wymagane tylko w trybie ręcznym
input_audio_buffer.clearCzyści bufor audio bez jego przetwarzania
conversation.item.createDodaje element do rozmowy: wiadomość tekstową, wcześniejszą historię lub wynik wywołania funkcji
conversation.item.deleteUsuwa element rozmowy na podstawie jego identyfikatora
response.createProsi model o wygenerowanie odpowiedzi; automatyczne w trybie VAD, jawne w trybie ręcznym
response.cancelAnuluje generowaną odpowiedź

Dwa z tych komunikatów zasługują na bliższe przyjrzenie się. conversation.item.create to sposób na wstrzyknięcie kontekstu: używasz go do przywrócenia historii wcześniejszego połączenia na początku nowej sesji. Z kolei input_audio_buffer.clear przydaje się, gdy użytkownik wyraźnie nie powiedział nic wartego przetworzenia (np. odchrząknięcie wykryte przez zbyt czuły mikrofon) i wolisz zacząć od czystego bufora, niż pozwolić modelowi interpretować szum.

Co wysyła serwer

Strumień przychodzący jest bardziej ruchliwy, ponieważ dostarcza bieżący komentarz do każdego etapu przetwarzania.

ZdarzenieZnaczenie
session.createdSesja została otwarta
session.updatedZastosowano aktualizację konfiguracji
conversation.createdRozmowa została ustawiona
input_audio_buffer.speech_startedVAD wykrył, że użytkownik zaczął mówić
input_audio_buffer.speech_stoppedVAD wykrył, że użytkownik przestał mówić
input_audio_buffer.committedBufor audio został zatwierdzony, przez VAD lub ręcznie
response.createdGenerowana jest odpowiedź
response.output_audio.deltaFragment audio odpowiedzi, w formacie base64
response.output_audio.doneAudio odpowiedzi jest kompletne
response.output_audio_transcript.deltaStrumieniowa transkrypcja tekstowa audio
response.doneOdpowiedź jest całkowicie zakończona
conversation.item.input_audio_transcription.completedDostępna jest transkrypcja wiadomości użytkownika
response.text.deltaStrumieniowany tekst, dla odpowiedzi niewokalnych
response.function_call_arguments.deltaStrumieniowane argumenty wywołania funkcji
response.function_call_arguments.doneWywołanie funkcji jest kompletne i gotowe do uruchomienia
errorWystąpił błąd; większość błędów można naprawić

To ostatnie wymaga ostrzeżenia. Otrzymanie error nie oznacza utraty sesji. Zgodnie z dokumentacją referencyjną xAI, większość błędów można naprawić, a sesja pozostaje otwarta, więc klient, który zamyka połączenie przy pierwszym error, przerywa rozmowę, która mogłaby trwać dalej. Zaloguj błąd, poinformuj użytkownika w razie potrzeby, ale utrzymuj gniazdo otwarte.

Szkielet klienta

W praktyce wszystko sprowadza się do instrukcji switch na msg.type. Oto minimalna postać klienta w JavaScript:

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

  switch (msg.type) {
    case "session.created":
      // Wyślij session.update z konfiguracją
      break;

    case "input_audio_buffer.speech_started":
      // Użytkownik mówi: zatrzymaj odtwarzane audio odpowiedzi
      break;

    case "response.output_audio.delta":
      // Zdekoduj base64 i odtwórz audio
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Uruchom funkcję i wyślij wynik z powrotem
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Błąd Voice Agent:", msg.error);
      break;
  }
};

Cztery gałęzie wystarczą do uruchomienia agenta: skonfiguruj przy otwarciu sesji, zareaguj, gdy użytkownik zacznie mówić, odtwarzaj przychodzące audio i uruchamiaj funkcje. Pozostałe zdarzenia wzbogacają interfejs i mogą poczekać na drugą iterację.

Trudna część: przerwanie

Barge-in, czyli sytuacja, gdy użytkownik zaczyna mówić, podczas gdy agent wciąż odpowiada, to moment, w którym ujawnia się niedbała implementacja. Serwer sam anuluje bieżącą odpowiedź i zaczyna generować nową na podstawie tego, co właśnie usłyszał. Jednak podczas gdy serwer przestał wysyłać dane, Twoja aplikacja nadal posiada w buforze wyjściowym kilka sekund już otrzymanego audio.

Jeśli nic nie zrobisz, użytkownik będzie nadal słyszeć zdanie, które właśnie przerwał, mówiąc поверх niego, a agent będzie sprawiał wrażenie, że nie słucha. Dlatego zaraz po otrzymaniu speech_started zatrzymaj odtwarzane audio, wyczyść bufor wyjściowy, aby nie odtwarzać nieaktualnego dźwięku, i pozwól serwerowi przetworzyć nowe dane wejściowe. Te dwa kroki zajmują kilka linii kodu, a robią całą różnicę między agentem, którego można przerwać, a takim, który mówi do pustki.

Kluczowe wnioski

  • Zdarzenia klienta obejmują konfigurację, wysyłanie audio, zarządzanie rozmową i kontrolowanie odpowiedzi
  • Zdarzenia serwera raportują wykrywanie mowy, fragmenty audio, transkrypcje i wywołania funkcji
  • VAD automatycznie obsługuje przerwanie (barge-in)
  • Większość zdarzeń error można naprawić: nie zamykaj połączenia, obsłuż błąd
  • W trybie ręcznym musisz jawnie wywołać commit, a następnie response.create