WebSocket-events beheersen
Op deze pagina
Een gesprek opgebouwd uit JSON-events
Onder de motorkap is een spraakuitwisseling met de Voice Agent niets meer dan een stroom JSON-berichten die in beide richtingen vloeien via de WebSocket-verbinding. Elk bericht bevat een type-veld dat aangeeft wat het is. Zolang u deze vocabulaire niet kent, werkt uw client op goed geluk. Zodra u ze wel kent, weet u precies waar u moet ingrijpen om een antwoord af te breken, een transcript weer te geven of te herstellen na een fout.
Events vallen in twee families, afhankelijk van de reisrichting. Diegene die u verstuurt, sturen de sessie aan; diegene die u ontvangt, vertellen u wat er op de server gebeurt.
Wat uw app verstuurt
Uw uitgaande berichten dekken vier behoeften: de sessie configureren, de audiobuffer voeden, de gespreksgeschiedenis beheren en het genereren van antwoorden sturen.
| Event | Doel |
|---|---|
session.update | Configureert of herconfigureert de sessie (spraak, instructies, tools, VAD, audioformaat) |
input_audio_buffer.append | Verstuurt een base64-gecodeerd audiofragment, continu terwijl de gebruiker spreekt |
input_audio_buffer.commit | Bevestigt de huidige bufferinhoud als bericht van de gebruiker; alleen nodig in handmatige modus |
input_audio_buffer.clear | Maakt de audiobuffer leeg zonder deze te verwerken |
conversation.item.create | Voegt een item toe aan het gesprek: een tekstbericht, eerdere geschiedenis of het resultaat van een functieaanroep |
conversation.item.delete | Verwijdert een gespreksitem op basis van de ID |
response.create | Vraagt het model een antwoord te genereren; automatisch in VAD-modus, expliciet in handmatige modus |
response.cancel | Breekt een antwoord af dat wordt gegenereerd |
Twee van deze berichten verdienen nadere aandacht. conversation.item.create is de manier om context injecteren: dit gebruikt u om de geschiedenis van een eerder gesprek te herstellen aan het begin van een nieuwe sessie. Wat input_audio_buffer.clear betreft, komt dit van pas wanneer de gebruiker duidelijk niets gezegd heeft dat verwerking waard is (een keelschraap opgepikt door een te gevoelige microfoon) en u liever opnieuw begint met een schone buffer dan het model ruis laat interpreteren.
Wat de server terugstuurt
De inkomende stroom is drukker, omdat deze een lopend commentaar geeft op elke verwerkingsstap.
| Event | Betekenis |
|---|---|
session.created | De sessie is geopend |
session.updated | Een configuratie-update is toegepast |
conversation.created | Het gesprek is ingesteld |
input_audio_buffer.speech_started | VAD detecteert dat de gebruiker is begonnen met spreken |
input_audio_buffer.speech_stopped | VAD detecteert dat de gebruiker is gestopt met spreken |
input_audio_buffer.committed | De audiobuffer is bevestigd, door VAD of handmatig |
response.created | Een antwoord wordt gegenereerd |
response.output_audio.delta | Een fragment van het antwoordaudio, in base64 |
response.output_audio.done | De antwoordaudio is voltooid |
response.output_audio_transcript.delta | Het teksttranscript van de audio, gestreamd |
response.done | Het antwoord is volledig voltooid |
conversation.item.input_audio_transcription.completed | Het transcript van het bericht van de gebruiker is beschikbaar |
response.text.delta | Gestreamde tekst, voor niet-spraakantwoorden |
response.function_call_arguments.delta | De argumenten van een functieaanroep, gestreamd |
response.function_call_arguments.done | De functieaanroep is voltooid en klaar om uit te voeren |
error | Er is een fout opgetreden; de meeste fouten zijn herstelbaar |
Dat laatste verdient een waarschuwing. Het ontvangen van error betekent niet dat de sessie verloren is. Volgens de xAI-referentie zijn de meeste fouten herstelbaar en blijft de sessie open, dus een client die de verbinding sluit bij de eerste error verbreekt een gesprek dat had kunnen doorgaan. Log het, informeer de gebruiker indien nodig, maar houd de socket open.
Het skelet van een client
In de praktijk komt alles neer op een switch op msg.type. Hier is de minimale vorm van een JavaScript-client:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Stuur session.update met de configuratie
break;
case "input_audio_buffer.speech_started":
// De gebruiker spreekt: stop de afspelende antwoordaudio
break;
case "response.output_audio.delta":
// Decodeer de base64 en speel de audio af
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Voer de functie uit en stuur het resultaat terug
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent-fout:", msg.error);
break;
}
};
Vier takken volstaan om een agent te laten draaien: configureer bij het openen van de sessie, reageer wanneer de gebruiker begint te spreken, speel inkomende audio af en voer functies uit. De andere events verrijken de interface en kunnen wachten op een tweede iteratie.
Het lastige deel: onderbrekingen
Barge-in, wanneer de gebruiker begint te praten terwijl de agent nog antwoordt, is waar een slordige implementatie door de mand valt. De server annuleert het huidige antwoord zelfstandig en begint een nieuw te genereren op basis van wat het zojuist heeft gehoord. Maar terwijl de server is gestopt met verzenden, houdt uw app nog steeds enkele seconden aan reeds ontvangen audio vast in de uitvoerbuffer.
Als u niets doet, blijft de gebruiker de zin horen die ze zojuist hebben onderbroken terwijl ze erdoorheen praten, en komt de agent over alsof hij niet luistert. Stop dus zodra u speech_started ontvangt de afspelende audio, leeg de uitvoerbuffer zodat u geen verouderd geluid afspeelt, en laat de server de nieuwe input verwerken. Die twee stappen kosten enkele regels code en maken het verschil tussen een agent die u kunt onderbreken en een die in het luchtledige praat.
Belangrijkste punten
- Client-events dekken configuratie, het verzenden van audio, het beheren van het gesprek en het sturen van antwoorden
- Server-events rapporteren spraakdetectie, audiofragmenten, transcripten en functieaanroepen
- VAD behandelt onderbrekingen (barge-in) automatisch
- De meeste
error-events zijn herstelbaar: sluit de verbinding niet, maar handel de fout af - In handmatige modus moet u
commiten vervolgensresponse.createexpliciet aanroepen