WebSocket-Ereignisse beherrschen
Auf dieser Seite
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.
| Ereignis | Zweck |
|---|---|
session.update | Konfiguriert oder neu konfiguriert die Sitzung (Stimme, Anweisungen, Tools, VAD, Audioformat) |
input_audio_buffer.append | Sendet einen base64-kodierten Audio-Abschnitt, kontinuierlich, während der Nutzer spricht |
input_audio_buffer.commit | Bestätigt den aktuellen Pufferinhalt als Nachricht des Nutzers; nur im manuellen Modus erforderlich |
input_audio_buffer.clear | Leert den Audio-Puffer ohne Verarbeitung |
conversation.item.create | Fügt einem Gespräch einen Eintrag hinzu: eine Textnachricht, frühere Historie oder das Ergebnis eines Funktionsaufrufs |
conversation.item.delete | Löscht einen Gesprächseintrag anhand seiner ID |
response.create | Fordert das Modell auf, eine Antwort zu generieren; automatisch im VAD-Modus, explizit im manuellen Modus |
response.cancel | Storniert 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.
| Ereignis | Bedeutung |
|---|---|
session.created | Die Sitzung ist geöffnet |
session.updated | Eine Konfigurationsänderung wurde angewendet |
conversation.created | Das Gespräch ist eingerichtet |
input_audio_buffer.speech_started | VAD erkennt, dass der Nutzer mit dem Sprechen begonnen hat |
input_audio_buffer.speech_stopped | VAD erkennt, dass der Nutzer mit dem Sprechen aufgehört hat |
input_audio_buffer.committed | Der Audio-Puffer wurde bestätigt, entweder durch VAD oder manuell |
response.created | Eine Antwort wird generiert |
response.output_audio.delta | Ein Abschnitt der Antwort-Audio, base64-kodiert |
response.output_audio.done | Die Antwort-Audio ist vollständig |
response.output_audio_transcript.delta | Der Text-Transkript des Audios, gestreamt |
response.done | Die Antwort ist vollständig abgeschlossen |
conversation.item.input_audio_transcription.completed | Das Transkript der Nachricht des Nutzers ist verfügbar |
response.text.delta | Gestreamter Text, für nicht-stimmliche Antworten |
response.function_call_arguments.delta | Die Argumente eines Funktionsaufrufs, gestreamt |
response.function_call_arguments.done | Der Funktionsaufruf ist abgeschlossen und bereit zur Ausführung |
error | Ein 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
commitund dannresponse.createexplizit aufrufen