Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

WebSocket-Ereignisse beherrschen

Lektion 4 von 14 Aktualisiert am 29. Juli 2026 Mittelstufe
Auf dieser Seite
  1. Ein Gespräch aus JSON-Ereignissen
  2. Was Ihre Anwendung sendet
  3. Was der Server zurücksendet
  4. Das Gerüst eines Clients
  5. Der knifflige Teil: Unterbrechungen
  6. Kernaussagen

Ein Gespräch aus JSON-Ereignissen

Im Hintergrund besteht ein Voice-Audio-Austausch mit dem Voice Agent lediglich aus einem Strom von JSON-Nachrichten, die in beide Richtungen über die WebSocket-Verbindung fließen. Jede Nachricht verfügt über ein type-Feld, das angibt, worum es sich handelt. Solange Sie dieses Vokabular nicht kennen, arbeitet Ihr Client eher durch Zufall. Sobald Sie es beherrschen, wissen Sie genau, wo Sie eingreifen müssen, um eine Antwort abzubrechen, eine Transkription anzuzeigen oder von einem Fehler zu recover.

Ereignisse lassen sich in zwei Familien einteilen, abhängig von ihrer Richtung. Die von Ihnen gesendeten Nachrichten steuern die Sitzung; die von Ihnen empfangenen geben Auskunft darüber, was auf dem Server passiert.

Was Ihre Anwendung sendet

Ihre ausgehenden Nachrichten decken vier Bedürfnisse ab: Konfiguration der Sitzung, Zufuhr des Audio-Puffers, Verwaltung der Gesprächshistorie und Steuerung der Antwortgenerierung.

EreignisZweck
session.updateKonfiguriert oder neu konfiguriert die Sitzung (Stimme, Anweisungen, Tools, VAD, Audioformat)
input_audio_buffer.appendSendet einen base64-kodierten Audio-Abschnitt, kontinuierlich, während der Nutzer spricht
input_audio_buffer.commitBestätigt den aktuellen Pufferinhalt als Nachricht des Nutzers; nur im manuellen Modus erforderlich
input_audio_buffer.clearLeert den Audio-Puffer ohne Verarbeitung
conversation.item.createFügt einem Gespräch einen Eintrag hinzu: eine Textnachricht, frühere Historie oder das Ergebnis eines Funktionsaufrufs
conversation.item.deleteLöscht einen Gesprächseintrag anhand seiner ID
response.createFordert das Modell auf, eine Antwort zu generieren; automatisch im VAD-Modus, explizit im manuellen Modus
response.cancelStorniert eine generierte Antwort

Zwei dieser Nachrichten verdienen einen genaueren Blick. conversation.item.create ist der Weg, um Kontext einzufügen: Damit stellen Sie die Historie eines früheren Anrufs am Beginn einer neuen Sitzung wieder her. Was input_audio_buffer.clear betrifft, so ist er nützlich, wenn der Nutzer eindeutig nichts gesagt hat, das verarbeitet werden sollte (ein Kehlkopfklappen, das von einem zu empfindlichen Mikrofon aufgenommen wurde), und Sie lieber mit einem sauberen Puffer neu beginnen möchten, statt dass das Modell Rauschen interpretiert.

Was der Server zurücksendet

Der eingehende Strom ist geschäftiger, da er eine laufende Kommentierung zu jedem Verarbeitungsschritt liefert.

EreignisBedeutung
session.createdDie Sitzung ist geöffnet
session.updatedEine Konfigurationsänderung wurde angewendet
conversation.createdDas Gespräch ist eingerichtet
input_audio_buffer.speech_startedVAD erkennt, dass der Nutzer mit dem Sprechen begonnen hat
input_audio_buffer.speech_stoppedVAD erkennt, dass der Nutzer mit dem Sprechen aufgehört hat
input_audio_buffer.committedDer Audio-Puffer wurde bestätigt, entweder durch VAD oder manuell
response.createdEine Antwort wird generiert
response.output_audio.deltaEin Abschnitt der Antwort-Audio, base64-kodiert
response.output_audio.doneDie Antwort-Audio ist vollständig
response.output_audio_transcript.deltaDer Text-Transkript des Audios, gestreamt
response.doneDie Antwort ist vollständig abgeschlossen
conversation.item.input_audio_transcription.completedDas Transkript der Nachricht des Nutzers ist verfügbar
response.text.deltaGestreamter Text, für nicht-stimmliche Antworten
response.function_call_arguments.deltaDie Argumente eines Funktionsaufrufs, gestreamt
response.function_call_arguments.doneDer Funktionsaufruf ist abgeschlossen und bereit zur Ausführung
errorEin Fehler ist aufgetreten; die meisten Fehler sind beherrschbar

Letzteres verdient eine Warnung. Das Empfangen von error bedeutet nicht, dass die Sitzung verloren ist. Laut der xAI-Referenz sind die meisten Fehler beherrschbar, und die Sitzung bleibt offen; ein Client, der die Verbindung beim ersten error schließt, bricht ein Gespräch ab, das hätte weiterlaufen können. Protokollieren Sie den Fehler, informieren Sie den Nutzer gegebenenfalls, halten Sie aber den Socket offen.

Das Gerüst eines Clients

In der Praxis kommt es allesamt auf einen Switch bei msg.type an. Hier ist die minimale Form eines JavaScript-Clients:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // Senden Sie session.update mit der Konfiguration
      break;

    case "input_audio_buffer.speech_started":
      // Der Nutzer spricht: Stoppen Sie das abspielende Antwort-Audio
      break;

    case "response.output_audio.delta":
      // Decodieren Sie das base64 und spielen Sie das Audio ab
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Führen Sie die Funktion aus und senden Sie das Ergebnis zurück
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Voice Agent error:", msg.error);
      break;
  }
};

Vier Zweige reichen aus, um einen Agenten zu betreiben: Konfigurieren Sie beim Öffnen der Sitzung, reagieren Sie, wenn der Nutzer mit dem Sprechen beginnt, spielen Sie eingehendes Audio ab und führen Sie Funktionen aus. Die anderen Ereignisse bereichern die Schnittstelle und können auf eine zweite Iteration warten.

Der knifflige Teil: Unterbrechungen

Barge-in, wenn der Nutzer zu sprechen beginnt, während der Agent noch antwortet, ist der Punkt, an dem eine schlampige Implementierung auffällt. Der Server storniert die aktuelle Antwort von sich aus und beginnt, eine neue basierend auf dem gerade Gehörten zu generieren. Während der Server jedoch das Senden eingestellt hat, hält Ihre Anwendung immer noch mehrere Sekunden bereits empfangenes Audio in ihrem Ausgabe-Puffer.

Wenn Sie nichts tun, hört der Nutzer den Satz weiter, den er gerade unterbrochen hat, während er darüber spricht, und der Agent wirkt nicht zuhören. Sobald Sie also speech_started empfangen, stoppen Sie das abspielende Audio, leeren Sie den Ausgabe-Puffer, damit kein veraltetes Sound-Signal abgespielt wird, und lassen Sie den Server den neuen Input verarbeiten. Diese beiden Schritte benötigen nur wenige Zeilen Code und machen den Unterschied zwischen einem Agenten, den man unterbrechen kann, und einem, der in die Leere spricht.

Kernaussagen

  • Client-Ereignisse decken Konfiguration, Senden von Audio, Verwaltung des Gesprächs und Steuerung von Antworten ab
  • Server-Ereignisse melden Spracherkennung, Audio-Abschnitte, Transkripte und Funktionsaufrufe
  • VAD behandelt Unterbrechungen (Barge-in) automatisch
  • Die meisten error-Ereignisse sind beherrschbar: Schließen Sie die Verbindung nicht, sondern behandeln Sie den Fehler
  • Im manuellen Modus müssen Sie commit und dann response.create explizit aufrufen