Opanuj zdarzenia WebSocket
Na tej stronie
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.
| Zdarzenie | Cel |
|---|---|
session.update | Konfiguruje lub rekonfiguruje sesję (głos, instrukcje, narzędzia, VAD, format audio) |
input_audio_buffer.append | Wysyła fragment audio zakodowany w base64, ciągle podczas mówienia użytkownika |
input_audio_buffer.commit | Zatwierdza bieżącą zawartość bufora jako wiadomość użytkownika; wymagane tylko w trybie ręcznym |
input_audio_buffer.clear | Czyści bufor audio bez jego przetwarzania |
conversation.item.create | Dodaje element do rozmowy: wiadomość tekstową, wcześniejszą historię lub wynik wywołania funkcji |
conversation.item.delete | Usuwa element rozmowy na podstawie jego identyfikatora |
response.create | Prosi model o wygenerowanie odpowiedzi; automatyczne w trybie VAD, jawne w trybie ręcznym |
response.cancel | Anuluje 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.
| Zdarzenie | Znaczenie |
|---|---|
session.created | Sesja została otwarta |
session.updated | Zastosowano aktualizację konfiguracji |
conversation.created | Rozmowa została ustawiona |
input_audio_buffer.speech_started | VAD wykrył, że użytkownik zaczął mówić |
input_audio_buffer.speech_stopped | VAD wykrył, że użytkownik przestał mówić |
input_audio_buffer.committed | Bufor audio został zatwierdzony, przez VAD lub ręcznie |
response.created | Generowana jest odpowiedź |
response.output_audio.delta | Fragment audio odpowiedzi, w formacie base64 |
response.output_audio.done | Audio odpowiedzi jest kompletne |
response.output_audio_transcript.delta | Strumieniowa transkrypcja tekstowa audio |
response.done | Odpowiedź jest całkowicie zakończona |
conversation.item.input_audio_transcription.completed | Dostępna jest transkrypcja wiadomości użytkownika |
response.text.delta | Strumieniowany tekst, dla odpowiedzi niewokalnych |
response.function_call_arguments.delta | Strumieniowane argumenty wywołania funkcji |
response.function_call_arguments.done | Wywołanie funkcji jest kompletne i gotowe do uruchomienia |
error | Wystą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ń
errormożna naprawić: nie zamykaj połączenia, obsłuż błąd - W trybie ręcznym musisz jawnie wywołać
commit, a następnieresponse.create