Konfigurieren einer Voice-Sitzung
Auf dieser Seite
Aktualisiert am 3. November 2026, basierend auf der xAI-Seite Speech to Speech und dem Voice-Prompting-Leitfaden. Quellen: Speech to Speech · Prompting Guide.
Die Nachricht, die alles bestimmt: session.update
Sobald die WebSocket-Verbindung aufgebaut ist, geschieht zunächst noch nichts. Die Nachricht session.update verleiht dem Agenten seine Identität: die Stimme, die er verwendet; die Anweisungen, die er befolgt; die Methode zur Erkennung von Sprechwechseln; und die Werkzeuge, die er aufrufen darf. Betrachten Sie dies als Geburtsurkunde der Sitzung. Alle weiteren Elemente der Konversation leiten sich daraus ab.
{
"type": "session.update",
"session": {
"instructions": "Sie sind ein professioneller Sprachassistent für ein E-Commerce-Unternehmen. Halten Sie Ihre Antworten kurz und helfen Sie Kunden bei ihren Bestellungen.",
"voice": "Ara",
"turn_detection": {
"type": "server_vad"
},
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
},
"tools": [
{ "type": "web_search" }
]
}
}
Der Server bestätigt dies mit einem session.updated-Ereignis. Sie müssen diese Nachricht nicht nur einmal senden. Sie können sie mitten in der Konversation erneut senden, um eine Einstellung sofort zu ändern. Beispielsweise können Sie die Stimme wechseln, wenn der Anruf vom Vertrieb in den technischen Support übergeht, ohne die Verbindung jemals zu unterbrechen.
Schreiben Sie Anweisungen für das Ohr, nicht für das Auge
Das Feld instructions übernimmt die Rolle des System-Prompts. Verwenden Sie es, um die Persönlichkeit des Agenten (formell, locker, technisch), die behandelbaren Themen, die Beschränkungen seiner Antworten (Länge, Format, Sprache) und den geschäftlichen Kontext festzulegen: Ihren Firmennamen, das Produktangebot und interne Verfahren.
Das Problem ist, dass ein guter geschriebener Prompt für einen Sprachagenten oft schlecht funktioniert. Wenn ein Modell allein gelassen wird, schreibt es Antworten mit zehn Zeilen. Wenn diese laut vorgelesen werden, ziehen sie sich in die Länge, und der Nutzer schaltet sich aus, bevor das Ende erreicht ist. Fordern Sie daher explizit kurze, direkte Antworten an. Wenn Ihre App in einer einzigen Sprache arbeitet, geben Sie diese an, sonst könnte der Agent die Sprache wechseln, um dem Akzent des Anrufers anzupassen. Und sagen Sie ihm, was er tun soll, wenn er etwas nicht versteht: Eine Anweisung wie „Stellen Sie eine präzisierende Frage, statt zu raten”, verhindert, dass eine falsch gehörte Bestellnummer eine unnötige Suche auslöst. Der xAI-Voice-Prompting-Leitfaden schlägt sogar eine fünfteilige Struktur vor (Rolle und Persona, Ziel, Gesprächsablauf, Sicherheitsvorkehrungen und Eskalation, Stimmlage) und empfiehlt pro Sprechwechsel ein oder zwei kurze Sätze, es sei denn, der Anrufer bittet um weitere Details.
Erkennung von Sprechwechseln
Der Block turn_detection entscheidet, wer spricht und wann. Die xAI-Dokumentation bietet hierfür nur zwei Einstellungen. Die erste ist type. Im Modus "server_vad" erkennt der Server das Ende jeder Äußerung selbstständig, speichert das Audio, startet die Antwort und behandelt Unterbrechungen: Sie müssen lediglich Audio mit input_audio_buffer.append senden. Die zweite Einstellung, idle_timeout_ms, ist optional. Bleibt der Nutzer nach einer Antwort für so viele Millisekunden schweigen, fordert der Server ihn erneut auf, und wiederholt dies nach jedem neuen Schweigen derselben Länge.
{
"turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}
Es gibt keinen Empfindlichkeitsschwellenwert oder eine Schweigedauer, die man justieren müsste. Die Parameter threshold, silence_duration_ms und prefix_padding_ms, die Sie in Beispielen für die OpenAI Realtime API sehen, tauchen in der xAI-Dokumentation nicht auf.
Falls das automatische Verhalten nicht Ihren Anforderungen entspricht, setzen Sie den Typ auf null und übernehmen Sie die Kontrolle. Dann liegt es an Ihnen, das Audio mit input_audio_buffer.append zu puffern, den Sprechwechsel explizit mit input_audio_buffer.commit zu bestätigen und die Generierung mit response.create auszulösen. Der manuelle Modus ist die richtige Wahl für eine Push-to-Talk-Oberfläche oder whenever Sie eine präzise Kontrolle darüber wünschen, wann der Agent spricht.
Wählen Sie das richtige Audioformat
Der Block audio legt die Eingabe- und Ausgabeformate unabhängig voneinander fest:
{
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
Es werden vier Typen akzeptiert. Wenn Sie keinen angeben, erhalten Sie PCM mit 24.000 Hz:
| Typ | Kodierung | Abtastfrequenzen |
|---|---|---|
audio/pcm | PCM Linear16, Little-Endian | 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz |
audio/pcmu | G.711 mu-law (Nordamerikanische Fernmelde) | Nur 8000 Hz |
audio/pcma | G.711 A-law (Europäische Fernmelde) | Nur 8000 Hz |
audio/opus | Opus, ein Paket pro Nachricht | 24000 Hz |
Ihr Übertragungskanal entscheidet. Eine Web-App im Browser kommt mit 24.000 Hz PCM gut zurecht, ein guter Kompromiss zwischen wahrgenommener Qualität und Bandbreite. Eine SIP-Telefon-Integration hat keine Wahl: Das Netzwerk transportiert G.711 mit 8.000 Hz, und das Erzwingen eines höherwertigen Formats führt nur zu einer sinnlosen Umwandlung.
Geben Sie dem Agenten Werkzeuge
Das Array tools listet auf, welche Werkzeuge der Agent während der Konversation aufrufen darf, und Sie können verschiedene Arten in derselben Sitzung mischen:
{
"tools": [
{ "type": "web_search" },
{ "type": "x_search", "allowed_x_handles": ["gaborit_music"] },
{
"type": "function",
"name": "get_order_status",
"parameters": {
"type": "object",
"properties": {
"order_id": { "type": "string" }
},
"required": ["order_id"]
}
}
]
}
Sie stellen das Werkzeugset bereit; der Agent wählt das Werkzeug. Während sich die Konversation entwickelt, entscheidet er, dass eine Frage nach den Nachrichten eine Websuche erfordert, während eine Bestellnummer get_order_status aufruft. Ihre Aufgabe besteht also weniger darin, Aufrufe zu orchestrieren, sondern darin, jedes Werkzeug klar zu beschreiben, damit der Agent die richtige Wahl trifft.
Kernaussagen
- Die Nachricht
session.updatekonfiguriert die Stimme, Anweisungen, VAD und Werkzeuge - Serverseitige VAD (
server_vad) erkennt Sprechwechsel und behandelt Unterbrechungen;idle_timeout_msist die einzige Einstellung - Der manuelle Modus (
turn_detection.typeaufnullgesetzt) bietet präzise Kontrolle, beispielsweise bei Push-to-Talk - Audioformate PCM, G.711 und Opus decken sowohl Web- als auch Fernmeldeanwendungen ab
- Sie können die Konfiguration mitten in der Sitzung ändern, ohne die Verbindung zu unterbrechen