Master WebSocket-begivenheder
På denne side
En samtale bestående af JSON-begivenheder
Under motorhjelmen er en taleudveksling med Voice Agent blot en strøm af JSON-meddelelser, der flyder begge veje over WebSocket-forbindelsen. Hver meddelelse har et type-felt, der angiver, hvad det er. Indtil du kender dette ordforråd, fungerer din klient held og lykke. Når du først gør det, ved du præcis, hvor du skal gribe ind for at afbryde et svar, vise en transskription eller komme dig efter en fejl.
Begivenheder falder i to familier, afhængigt af hvilken vej de rejser. Dem, du sender, styrer sessionen; dem, du modtager, fortæller dig, hvad der sker på serveren.
Hvad din app sender
Dine udgående meddelelser dækker fire behov: konfigurering af sessionen, fodring af lydbufferen, styring af samtaleshistorikken og kontrol af svar-generering.
| Begivenhed | Formål |
|---|---|
session.update | Konfigurerer eller rekonfigurerer sessionen (stemme, instrukser, værktøjer, VAD, lydformat) |
input_audio_buffer.append | Sender en base64-kodet lydbid kontinuerligt, mens brugeren taler |
input_audio_buffer.commit | Bekræfter det aktuelle bufferindhold som brugerens besked; kun nødvendigt i manuel tilstand |
input_audio_buffer.clear | Tømmer lydbufferen uden at behandle den |
conversation.item.create | Tilføjer et element til samtalen: en tekstbesked, tidligere historik eller resultatet af et funktionskald |
conversation.item.delete | Sletter et samtaleelement ved dets ID |
response.create | Beder modellen om at generere et svar; automatisk i VAD-tilstand, eksplicit i manuel tilstand |
response.cancel | Annullerer et svar, der er under generering |
To af disse meddelelser fortjener et nærmere kig. conversation.item.create er måden, du injicerer kontekst på: det er det, du bruger til at gendanne historikken fra et tidligere opkald ved starten af en ny session. Hvad angår input_audio_buffer.clear, kommer den til nytte, når brugeren tydeligvis ikke sagde noget værd at behandle (en halsrydning opfanget af en alt for følsom mikrofon), og du hellere vil starte forfra med en ren buffer end lade modellen fortolke støj.
Hvad serveren sender tilbage
Den indgående strøm er mere travl, fordi den giver en løbende kommentar til hvert behandlingstrin.
| Begivenhed | Betydning |
|---|---|
session.created | Sessionen er åben |
session.updated | En konfigurationsopdatering er blevet anvendt |
conversation.created | Samtalen er opsat |
input_audio_buffer.speech_started | VAD registrerer, at brugeren er begyndt at tale |
input_audio_buffer.speech_stopped | VAD registrerer, at brugeren er holdt op med at tale |
input_audio_buffer.committed | Lydbufferen er bekræftet, enten af VAD eller manuelt |
response.created | Et svar er under generering |
response.output_audio.delta | En bid af svarets lyd, i base64 |
response.output_audio.done | Svarets lyd er fuldført |
response.output_audio_transcript.delta | Teksttransskriptionen af lyden, streamet |
response.done | Svaret er helt fuldført |
conversation.item.input_audio_transcription.completed | Transskriptionen af brugerens besked er tilgængelig |
response.text.delta | Streamet tekst, til ikke-talebaserede svar |
response.function_call_arguments.delta | Argumenterne til et funktionskald, streamet |
response.function_call_arguments.done | Funktionskaldet er fuldført og klar til at køre |
error | Der opstod en fejl; de fleste fejl kan gendannes |
Den sidste kræver en advarsel. At modtage error betyder ikke, at sessionen er tabt. Ifølge xAI-referencen er de fleste fejl genoprettelige, og sessionen forbliver åben, så en klient, der lukker forbindelsen ved den første error, ødelægger en samtale, der kunne have fortsat. Log den, fortæl brugeren det, hvis det er nødvendigt, men hold sokklen åben.
Skelettet af en klient
I praksis handler alt om et switch på msg.type. Her er den minimale form for en JavaScript-klient:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Send session.update med konfigurationen
break;
case "input_audio_buffer.speech_started":
// Brugeren taler: stop det svar-lyd, der afspilles
break;
case "response.output_audio.delta":
// Dekoder base64 og afspiller lyden
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Kør funktionen og send resultatet tilbage
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent-fejl:", msg.error);
break;
}
};
Fire grene er nok til at køre en agent: konfigurér, når sessionen åbnes, reagér, når brugeren begynder at tale, afspil indgående lyd, og kør funktioner. De andre begivenheder beriger grænsefladen og kan vente til en anden iteration.
Den svære del: Afbrydelser
Barge-in, når brugeren begynder at tale, mens agenten stadig svarer, er hvor en sjusket implementering viser sig. Serveren annullerer det aktuelle svar af sig selv og begynder at generere et nyt ud fra det, den lige har hørt. Men mens serveren er holdt op med at sende, har din app stadig flere sekunders allerede modtaget lyd i sin output-buffer.
Hvis du ikke gør noget, fortsætter brugeren med at høre den sætning, de lige afbrød, mens de taler hen over den, og agenten fremstår som om, den ikke lytter. Så snart du modtager speech_started, skal du derfor stoppe den lyd, der afspilles, tømme output-bufferen, så du ikke afspiller forældet lyd, og lade serveren behandle det nye input. Disse to trin tager få linjer kode og gør hele forskellen mellem en agent, du kan afbryde, og en, der taler ud i det tomme rum.
Vigtige pointer
- Klientbegivenheder dækker konfiguration, sending af lyd, styring af samtalen og kontrol af svar
- Serverbegivenheder rapporterer talegenkendelse, lydbidder, transskriptioner og funktionskald
- VAD håndterer afbrydelser (barge-in) automatisk
- De fleste
error-begivenheder kan gendannes: luk ikke forbindelsen, håndter fejlen - I manuel tilstand skal du eksplicit kalde
commitog derefterresponse.create