Savladaj WebSocket događaje
Na ovoj stranici
Razgovor sastavljen od JSON događaja
Ispod haube, glasovna razmjena s Voice Agentom nije ništa drugo do tok JSON poruka koji teče u oba smjera preko WebSocket veze. Svaka poruka ima polje type koje govori o čemu se radi. Dok ne naučiš taj rječnik, tvoj klijent radi na sreću. Čim ga savladaš, točno znaš gdje intervenirati da prekineš odgovor, prikažeš transkript ili se oporaviš od pogreške.
Događaji se dijele u dvije obitelji, ovisno o smjeru putovanja. Oni koje šalješ pokreću sesiju; oni koje primaš govore ti što se događa na poslužitelju.
Što tvoja aplikacija šalje
Tvoje odlazne poruke pokrivaju četiri potrebe: konfiguriranje sesije, punjenje audio međuspremnika, upravljanje poviješću razgovora i kontrolu generiranja odgovora.
| Događaj | Svrha |
|---|---|
session.update | Konfigurira ili rekonfigurira sesiju (glas, upute, alati, VAD, audio format) |
input_audio_buffer.append | Šalje dio audio zapisa kodiran u base64, kontinuirano dok korisnik govori |
input_audio_buffer.commit | Potvrđuje sadržaj trenutnog međuspremnika kao korisnikovu poruku; potrebno samo u ručnom načinu rada |
input_audio_buffer.clear | Prazni audio međuspremnik bez obrade |
conversation.item.create | Dodaje stavku u razgovor: tekstualnu poruku, raniju povijest ili rezultat poziva funkcije |
conversation.item.delete | Briše stavku razgovora prema njezinom ID-u |
response.create | Traži od modela da generira odgovor; automatski u VAD načinu, eksplicitno u ručnom načinu |
response.cancel | Poništava odgovor koji se generira |
Dvije od ovih poruka zaslužuju bliži pogled. conversation.item.create je način na koji ubacuješ kontekst: to koristiš za vraćanje povijesti ranijeg poziva na početku nove sesije. Što se tiče input_audio_buffer.clear, on je koristan kada korisnik očito nije rekao ništa vrijedno obrade (na primjer, kašalj uhvaćen preosjetljivim mikrofonom) i radije želiš krenuti ispočetka s praznim međuspremnikom nego dopustiti modelu da tumači šum.
Što poslužitelj šalje natrag
Dolazni tok je življi jer daje komentar u stvarnom vremenu za svaki korak obrade.
| Događaj | Značenje |
|---|---|
session.created | Sesija je otvorena |
session.updated | Ažuriranje konfiguracije je primijenjeno |
conversation.created | Razgovor je postavljen |
input_audio_buffer.speech_started | VAD detektira da je korisnik počeo govoriti |
input_audio_buffer.speech_stopped | VAD detektira da je korisnik prestao govoriti |
input_audio_buffer.committed | Audio međuspremnik je potvrđen, putem VAD-a ili ručno |
response.created | Generira se odgovor |
response.output_audio.delta | Dio odgovarajućeg audio zapisa, u base64 formatu |
response.output_audio.done | Audio odgovor je potpun |
response.output_audio_transcript.delta | Tekstualni transkript audio zapisa, strujno |
response.done | Odgovor je u potpunosti završen |
conversation.item.input_audio_transcription.completed | Transkript korisnikove poruke je dostupan |
response.text.delta | Strujni tekst, za odgovore koji nisu glasovni |
response.function_call_arguments.delta | Argumenti poziva funkcije, strujno |
response.function_call_arguments.done | Poziv funkcije je potpun i spreman za izvršavanje |
error | Došlo je do pogreške; većina pogrešaka je moguće oporaviti |
Posljednja stavka zahtijeva upozorenje. Primitak error ne znači da je sesija izgubljena. Prema xAI referenci, većina pogrešaka je moguće oporaviti i sesija ostaje otvorena, stoga klijent koji zatvori vezu pri prvoj error poruci prekida razgovor koji je mogao nastaviti. Zabilježi pogrešku, obavijesti korisnika ako je potrebno, ali drži socket otvorenim.
Kostur klijenta
U praksi, sve se svodi na switch naredbu temeljenu na msg.type. Evo minimalnog oblika JavaScript klijenta:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Pošalji session.update s konfiguracijom
break;
case "input_audio_buffer.speech_started":
// Korisnik govori: zaustavi reprodukciju audio odgovora
break;
case "response.output_audio.delta":
// Dekodiraj base64 i reproduciraj audio
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Pokreni funkciju i pošalji natrag rezultat
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent error:", msg.error);
break;
}
};
Četiri grane dovoljne su za pokretanje agenta: konfiguriraj pri otvaranju sesije, reagiraj kada korisnik počne govoriti, reproduciraj dolazni audio i pokreni funkcije. Ostali događaji obogaćuju sučelje i mogu pričekati drugu iteraciju.
Zamršeni dio: prekidi
Barge-in, situacija kada korisnik počne govoriti dok agent još odgovara, je trenutak u kojem se vidi loša implementacija. Poslužitelj samostalno poništava trenutni odgovor i počinje generirati novi na temelju onoga što je upravo čuo. No, dok je poslužitelj prestao slati, tvoja aplikacija i dalje drži nekoliko sekundi već primljenog audio zapisa u svom izlaznom međuspremniku.
Ako ne učiniš ništa, korisnik će i dalje čuti rečenicu koju je upravo prekinuo dok govori preko nje, a agent će djelovati kao da ne sluša. Stoga, čim primiš speech_started, zaustavi audio koji se reproducira, isprazni izlazni međuspremnik kako ne bi reproducirao zastarjeli zvuk i pusti poslužitelju da obradi novi unos. Ta dva koraka zahtijevaju nekoliko redaka koda, a čine svu razliku između agenta kojeg možeš prekinuti i onoga koji govori u prazninu.
Ključne točke
- Događaji klijenta pokrivaju konfiguraciju, slanje audija, upravljanje razgovorom i kontrolu odgovora
- Događaji poslužitelja izvještavaju o detekciji govora, audio dijelovima, transkriptima i pozivima funkcija
- VAD automatski rukuje prekidima (barge-in)
- Većina događaja
errorje moguće oporaviti: ne zatvaraj vezu, obradi pogrešku - U ručnom načinu rada, moraš eksplicitno pozvati
commit, a zatimresponse.create