Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Master WebSocket-begivenheder

Lektion 4 af 14 Opdateret 29. juli 2026 Mellem
På denne side
  1. En samtale bestående af JSON-begivenheder
  2. Hvad din app sender
  3. Hvad serveren sender tilbage
  4. Skelettet af en klient
  5. Den svære del: Afbrydelser
  6. Vigtige pointer

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.

BegivenhedFormål
session.updateKonfigurerer eller rekonfigurerer sessionen (stemme, instrukser, værktøjer, VAD, lydformat)
input_audio_buffer.appendSender en base64-kodet lydbid kontinuerligt, mens brugeren taler
input_audio_buffer.commitBekræfter det aktuelle bufferindhold som brugerens besked; kun nødvendigt i manuel tilstand
input_audio_buffer.clearTømmer lydbufferen uden at behandle den
conversation.item.createTilføjer et element til samtalen: en tekstbesked, tidligere historik eller resultatet af et funktionskald
conversation.item.deleteSletter et samtaleelement ved dets ID
response.createBeder modellen om at generere et svar; automatisk i VAD-tilstand, eksplicit i manuel tilstand
response.cancelAnnullerer 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.

BegivenhedBetydning
session.createdSessionen er åben
session.updatedEn konfigurationsopdatering er blevet anvendt
conversation.createdSamtalen er opsat
input_audio_buffer.speech_startedVAD registrerer, at brugeren er begyndt at tale
input_audio_buffer.speech_stoppedVAD registrerer, at brugeren er holdt op med at tale
input_audio_buffer.committedLydbufferen er bekræftet, enten af VAD eller manuelt
response.createdEt svar er under generering
response.output_audio.deltaEn bid af svarets lyd, i base64
response.output_audio.doneSvarets lyd er fuldført
response.output_audio_transcript.deltaTeksttransskriptionen af lyden, streamet
response.doneSvaret er helt fuldført
conversation.item.input_audio_transcription.completedTransskriptionen af brugerens besked er tilgængelig
response.text.deltaStreamet tekst, til ikke-talebaserede svar
response.function_call_arguments.deltaArgumenterne til et funktionskald, streamet
response.function_call_arguments.doneFunktionskaldet er fuldført og klar til at køre
errorDer 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 commit og derefter response.create