Behärska WebSocket-händelser
På denna sida
Ett samtal byggt av JSON-händelser
Under huven är ett röstsamtal med Voice Agent bara en ström av JSON-meddelanden som flödar båda vägarna över WebSocket-anslutningen. Varje meddelande har ett fält type som anger vad det är. Innan du kan denna terminologi fungerar din klient på tur och chans. När du väl behärskar den vet du exakt var du ska kliva in för att bryta ett svar, visa en transkription eller återhämta dig från ett fel.
Händelserna delas in i två familjer, beroende på vilken väg de färdas. De du skickar styr sessionen; de du tar emot berättar vad som händer på servern.
Vad din app skickar
Dina utgående meddelanden täcker fyra behov: konfigurera sessionen, mata ljudbufferten, hantera samtalshistoriken och styra svarsgenereringen.
| Händelse | Syfte |
|---|---|
session.update | Konfigurerar eller omkonfigurerar sessionen (röst, instruktioner, verktyg, VAD, ljudformat) |
input_audio_buffer.append | Skickar en base64-kodad ljudbit, kontinuerligt medan användaren talar |
input_audio_buffer.commit | Bekräftar buffertens aktuella innehåll som användarens meddelande; behövs endast i manuellt läge |
input_audio_buffer.clear | Tömmer ljudbufferten utan att bearbeta den |
conversation.item.create | Lägger till ett objekt i samtalet: ett textmeddelande, tidigare historik eller resultatet av ett funktionsanrop |
conversation.item.delete | Tar bort ett samtalsobjekt via dess ID |
response.create | Ber modellen att generera ett svar; automatiskt i VAD-läge, explicit i manuellt läge |
response.cancel | Avbryter ett svar som håller på att genereras |
Två av dessa meddelanden förtjänar en närmare titt. conversation.item.create är hur du injicerar kontext: det är vad du använder för att återställa historiken från ett tidigare samtal vid starten av en ny session. När det gäller input_audio_buffer.clear kommer den till nytta när användaren uppenbarligen inte sa något värt att bearbeta (ett harklande fångat av en överkänslig mikrofon) och du hellre vill börja om från en ren buffert än låta modellen tolka brus.
Vad servern skickar tillbaka
Den inkommande strömmen är livligare, eftersom den ger en löpande kommentar till varje bearbetningssteg.
| Händelse | Betydelse |
|---|---|
session.created | Sessionen är öppen |
session.updated | En konfigurationsuppdatering har tillämpats |
conversation.created | Samtalet är inställt |
input_audio_buffer.speech_started | VAD upptäcker att användaren har börjat tala |
input_audio_buffer.speech_stopped | VAD upptäcker att användaren har slutat tala |
input_audio_buffer.committed | Ljudbufferten har bekräftats, av VAD eller manuellt |
response.created | Ett svar håller på att genereras |
response.output_audio.delta | En bit av svars-ljudet, i base64 |
response.output_audio.done | Svars-ljudet är komplett |
response.output_audio_transcript.delta | Texttranskriptionen av ljudet, strömmad |
response.done | Svaret är helt avslutat |
conversation.item.input_audio_transcription.completed | Transkriptionen av användarens meddelande är tillgänglig |
response.text.delta | Strömmad text, för icke-röstsvar |
response.function_call_arguments.delta | Argumenten för ett funktionsanrop, strömmade |
response.function_call_arguments.done | Funktionsanropet är klart och redo att köras |
error | Ett fel har inträffat; de flesta fel går att återhämta sig från |
Den sista kräver en varning. Att ta emot error betyder inte att sessionen är förlorad. Enligt xAI:s referens är de flesta fel återställbara och sessionen förblir öppen, så en klient som stänger anslutningen vid första error bryter ett samtal som kunde ha fortsatt. Logga det, informera användaren vid behov, men håll socketen öppen.
Skelettet för en klient
I praktiken handlar allt om en switch på msg.type. Här är den minimala formen för en JavaScript-klient:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Skicka session.update med konfigurationen
break;
case "input_audio_buffer.speech_started":
// Användaren talar: stoppa svars-ljudet som spelas
break;
case "response.output_audio.delta":
// Avkoda base64 och spela ljudet
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Kör funktionen och skicka tillbaka resultatet
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent-fel:", msg.error);
break;
}
};
Fyra grenar räcker för att köra en agent: konfigurera när sessionen öppnas, reagera när användaren börjar tala, spela inkommande ljud och kör funktioner. De andra händelserna berikar gränssnittet och kan vänta till en andra iteration.
Den knepiga delen: avbrott
Barge-in, när användaren börjar tala medan agenten fortfarande svarar, är där en slarvig implementation avslöjas. Servern avbryter det aktuella svaret på egen hand och börjar generera ett nytt från det den just hört. Men medan servern har slutat skicka, har din app fortfarande flera sekunder av redan mottaget ljud i sin utmatningsbuffert.
Om du inte gör något fortsätter användaren att höra meningen de just avbröt medan de pratar över den, och agenten framstår som om den inte lyssnar. Så snart du tar emot speech_started måste du alltså stoppa ljudet som spelas, tömma utmatningsbufferten så att du inte spelar gammalt ljud, och låta servern bearbeta den nya inmatningen. Dessa två steg tar några rader kod och gör hela skillnaden mellan en agent du kan avbryta och en som pratar ut i tomma intet.
Viktiga punkter
- Klienthändelser täcker konfiguration, sändning av ljud, hantering av samtal och styrning av svar
- Serverhändelser rapporterar tal-detektering, ljudbitar, transkriptioner och funktionsanrop
- VAD hanterar avbrott (barge-in) automatiskt
- De flesta
error-händelser är återställbara: stäng inte anslutningen, hantera felet - I manuellt läge måste du explicit anropa
commitoch sedanresponse.create