Server-zu-Klient-Events
Auf dieser Seite
Die von Ihnen empfangenen Nachrichten
Der Server sendet zahlreiche Events, um Sie über den Zustand des Gesprächs zu informieren, das Antwort-Audio zu übermitteln und Fehler zu melden. Das Verständnis dieser Events ist unerlässlich, um eine reaktionsschnelle und zuverlässige Anwendung zu entwickeln.
Session- und Gesprächs-Events
Diese Events eintreffen, wenn die Verbindung aufgebaut wird, und nach jeder Konfigurationsänderung:
session.created: Die Sitzung ist geöffnet; das Event enthält die Sitzungskonfigurationsession.updated: Die Konfiguration wurde erfolgreich aktualisiertconversation.created: Der Gesprächskanal wurde eingerichtet
Audio-Puffer-Events
Diese Events informieren Sie über die Sprachaktivität, die der VAD (Voice Activity Detection) erkennt:
input_audio_buffer.speech_started: Der VAD erkennt, dass der Nutzer mit dem Sprechen begonnen hatinput_audio_buffer.speech_stopped: Der VAD erkennt das Ende der Spracheinput_audio_buffer.committed: Der Audio-Puffer wurde als Nachricht übermittelt
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// Der Nutzer spricht: Zeigen Sie einen visuellen Indikator
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// Der Nutzer hat aufgehört: Verstecken Sie den Indikator
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Die Audio-Nachricht wird verarbeitet
showProcessingIndicator(true);
break;
}
});
Antwort-Audio-Events
Das Antwort-Audio strömt über zwei Events zu.
response.output_audio.delta
Jedes Delta enthält ein base64-kodiertes Audio-Segment. Sammeln Sie diese Segmente und spielen Sie sie in der richtigen Reihenfolge ab:
{
"type": "response.output_audio.delta",
"delta": "SGVsbG8gV29ybGQ...",
"item_id": "item_resp_001",
"output_index": 0,
"content_index": 0
}
case "response.output_audio.delta":
const audioChunk = base64ToArrayBuffer(event.delta);
audioPlayer.enqueue(audioChunk);
break;
response.output_audio.done
Signalisiert, dass das gesamte Antwort-Audio gesendet wurde:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Transkriptions-Events
Die API kann sowohl das Audio des Nutzers als auch das Antwort-Audio transkribieren:
conversation.item.input_audio_transcription.completed: Ein Transkript dessen, was der Nutzer gesagt hatresponse.output_audio_transcript.delta: Ein gestreamtes Transkript der Antwort des Agents
case "conversation.item.input_audio_transcription.completed":
console.log("Der Nutzer sagte:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Text-Events
Wenn der Agent Text generiert (zusätzlich zu oder anstelle von Audio), erhalten Sie:
response.text.delta: Ein gestreamtes Textfragment
{
"type": "response.text.delta",
"delta": "Ihre Bestellung wurde"
}
Function-Calling-Events
Wenn der Agent beschließt, eine Funktion aufzurufen, werden zwei Events emittiert:
response.function_call_arguments.delta: Die Funktionsargumente, gestreamtresponse.function_call_arguments.done: Die vollständige Funktionsanfrage mit allen Argumenten
Lektion 13 zu Voice Function Calling behandelt diese Events im Detail.
response.done
Dieses Event markiert das vollständige Ende einer Antwort. Es enthält eine Zusammenfassung der Antwort, einschließlich Nutzungsstatistiken:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Das Fehler-Event
Dieses Event meldet Fehler. Gemäß der xAI-Referenz sind die meisten Fehler wiederherstellbar, und die WebSocket-Verbindung bleibt offen:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Ungültiges Audioformat angegeben"
}
}
Ihre Anwendung sollte diese Fehler protokollieren und je nach Schweregrad dem Nutzer eine Meldung anzeigen oder versuchen, das Problem automatisch zu beheben.
Wichtige Erkenntnisse
- Der Server sendet Events für jeden Schritt: Spracherkennung, Audio, Transkription, Text und Fehler
- Antwort-Audio kommt als base64-Segmente über
response.output_audio.deltaan - Transkripte sind sowohl für die Eingabe des Nutzers als auch für die Ausgabe des Agents verfügbar
response.donemarkiert das Ende einer vollständigen Antwort- Die meisten über das
error-Event gemeldeten Fehler sind wiederherstellbar: Die Verbindung bleibt offen