Konfigurieren Sie die Sitzung mit session.update
Auf dieser Seite
Aktualisiert am 3. November 2026, basierend auf den xAI-Seiten Speech to Speech und Text to Speech: 28 integrierte Stimmen, wobei
turn_detectionallein durch seintypefestgelegt wird (mit dem optionalenidle_timeout_ms). Quellen: Speech to Speech · Text to Speech.
Konfigurieren Sie Ihren Voice-Agenten
Sobald die WebSocket-Verbindung aufgebaut ist und Sie das session.created-Ereignis erhalten haben, konfigurieren Sie die Sitzung, indem Sie eine session.update-Nachricht senden. Hier definieren Sie, wie sich Ihr Voice-Agent verhält: seine Persönlichkeit, seine Stimme, die verfügbaren Werkzeuge und die Erkennung von Gesprächsrunden.
Die vollständige Struktur von session.update
Hier ist ein detailliertes Konfigurationsbeispiel:
{
"type": "session.update",
"session": {
"instructions": "Sie sind ein professioneller Sprachassistent für eine Anwaltskanzlei. Antworten Sie kurz und präzise. Verwenden Sie einen formellen Ton.",
"voice": "Rex",
"tools": [
{"type": "web_search"},
{
"type": "function",
"name": "look_up_case",
"description": "Ermittelt einen Kundenfall anhand der Nummer",
"parameters": {
"type": "object",
"properties": {
"case_number": {
"type": "string",
"description": "Nummer des Kundenfalls"
}
},
"required": ["case_number"]
}
}
],
"turn_detection": {
"type": "server_vad"
},
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
Die Einstellungen im Detail
Anweisungen (Systemprompt)
Das Feld instructions entspricht dem Systemprompt in den Text-APIs: Es definiert die Persönlichkeit, den Kontext und die Beschränkungen Ihres Voice-Agenten. Beim Verfassen gibt es jedoch eine spezifische Einschränkung für die Sprachkommunikation: Kürze. Jedes Token des Prompts wird vor der ersten Antwort verarbeitet, und ein ausufernder Prompt verursacht spürbare Latenz, sobald der Anruf verbunden ist. Halten Sie sich an das Wesentliche und überlassen Sie die Details Ihrer Anwendungslogik. Innerhalb dieses engen Budgets verdienen drei Dinge einen Platz. Der Ton (formell, freundlich, technisch), da der Voice-Agent die Marke buchstäblich im Ohr des Kunden verkörpert. Die Sprache: Geben Sie diese an („antworten Sie auf Englisch”), sonst folgt der Agent der Sprache des Nutzers oder der Frage. Und die Grenzen: Was der Agent tun kann und, vor allem, was er ablehnen oder an einen Menschen weitergeben muss, denn am Telefon geht eine außerhalb des Rahmens liegende Antwort aus, bevor jemand sie überprüfen kann.
Stimme
Die Einstellung voice akzeptiert eine von 28 integrierten Stimmen von xAI (Stand 3. November 2026), die sowohl vom Voice-Agenten als auch von der Text-zu-Sprache-Funktion geteilt werden, oder die ID einer benutzerdefinierten Stimme, die mit der Custom Voices API erstellt wurde. Stimmen-IDs sind nicht fallempfindlich: eve, Eve und EVE beziehen sich alle auf dieselbe Stimme. Jede Stimme spricht jede unterstützte Sprache.
Die fünf ursprünglichen Stimmen, wie xAI sie beschreibt:
- eve: energisch und aufgeweckt, britischer Akzent
- ara: warm und freundlich
- rex: selbstbewusst und klar
- sal: sanft und ausgewogen
- leo: autoritär und kraftvoll, britischer Akzent
Dreiundzwanzig neuere Stimmen schließen sich ihnen an: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora und liora. Sie können die aktuelle Liste mit dem Ton und den Anwendungsfällen jeder Stimme von GET /v1/tts/voices oder auf der xAI Text to Speech-Seite abrufen.
Werkzeuge
Das tools-Array definiert die Werkzeuge, die der Agent während des Gesprächs aufrufen kann. Sie können verschiedene Typen kombinieren: Websuche, X-Suche, benutzerdefinierte Funktionen, RAG-Sammlungen und MCP-Server. Die folgenden Lektionen behandeln Werkzeuge im Detail.
Audio-Konfiguration
Das audio-Objekt legt die Eingabe- und Ausgabeformate fest. Sie können für Eingabe und Ausgabe unterschiedliche Formate verwenden, wenn Ihre Architektur dies erfordert (beispielsweise G.711 von einem Telefon-System empfangen und PCM an einen Browser senden).
Aktualisieren Sie die Sitzung mitten im Gespräch
Sie können session.update mehrmals während eines Gesprächs senden. Dies ermöglicht es Ihnen, das Verhalten des Agenten auf dem Laufenden zu ändern:
// Ändern Sie die Stimme mitten im Gespräch
ws.send(JSON.stringify({
type: "session.update",
session: {
voice: "Ara"
}
}));
// Fügen Sie ein weiteres Werkzeug hinzu
ws.send(JSON.stringify({
type: "session.update",
session: {
tools: [
{ type: "web_search" },
{ type: "x_search" }
]
}
}));
Die xAI-Dokumentation unterstützt explizit Änderungen während der Sitzung für mehrere Einstellungen (Transkriptionssprache, Schlüsselwörter, Aussprachenersetzungen, Audio-Transport) und bestätigt diese mit session.updated: Prüfen Sie dies, um die angewandte Konfiguration zu bestätigen.
Kernaussagen
session.updateist die erste Nachricht, die nachsession.createdgesendet wird- Das Feld
instructionsdefiniert die Persönlichkeit und Beschränkungen des Agenten - 28 integrierte Stimmen sind verfügbar (einschließlich eve, ara, rex, sal und leo), plus benutzerdefinierte Stimmen
- Audio-Konfiguration und Werkzeuge sind anpassbar
- Sie können
session.updatemehrmals senden, um das Verhalten mitten im Gespräch zu ändern