Client-zu-Server-Ereignisse
Auf dieser Seite
Die von Ihnen gesendeten Nachrichten
Die Voice-Agent-API funktioniert durch den Austausch von JSON-Ereignissen über WebSocket. In dieser Lektion durchlaufen Sie jedes Ereignis, das Ihre Anwendung an den Server senden kann. Jedes Ereignis hat eine spezifische Rolle im Gesprächszyklus.
| Ereignis | Beschreibung | Wann verwenden |
|---|---|---|
| session.update | Konfigurieren der Sitzung | Beim Start und zur Änderung der Konfiguration |
| input_audio_buffer.append | Senden eines base64-Audio-Schnappschusses | Kontinuierlich während der Aufnahme |
| input_audio_buffer.commit | Festlegen des Audio-Puffers | Im Push-to-Talk-Modus |
| input_audio_buffer.clear | Leeren des Puffers ohne Verarbeitung | Zum Abbrechen einer Aufnahme |
| conversation.item.create | Hinzufügen einer Nachricht oder eines Funktionsergebnisses | Verlauf, Kontext, Funktionsergebnisse |
| conversation.item.delete | Löschen eines Elements nach ID | Aufräumen des Gesprächsverlaufs |
| response.create | Anfordern einer Antwort | Im manuellen Modus (automatisch mit VAD) |
| response.cancel | Abbrechen einer laufenden Antwort | Wenn der Nutzer unterbricht |
conversation.item.create
Dieses Ereignis ermöglicht es Ihnen, Nachrichten in das Gespräch einzufügen, ohne den Audio-Stream zu durchlaufen. Es deckt drei Hauptfälle ab.
Hinzufügen einer Benutzertextnachricht
{
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "Was ist der Status meiner Bestellung 12345?"
}
]
}
}
Gesprächsverlauf einfügen
Bevor das Sprachgespräch beginnt, können Sie den Verlauf mit früheren Austauschvorgängen vorbefüllen, um dem Agenten Kontext zu geben:
{
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hallo, ich bin Ihr Assistent. Wie kann ich Ihnen helfen?"
}
]
}
}
Rückgabe eines Funktionsergebnisses
Nachdem eine Funktionsausführung abgeschlossen wurde, senden Sie das Ergebnis mit diesem Ereignis zurück (siehe Lektion 13 zum Funktionsaufruf):
{
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": "call_abc123",
"output": "{\"status\": \"shipped\", \"tracking\": \"FR123456789\"}"
}
}
conversation.item.delete
Löscht ein Gesprächselement nach seiner ID:
{
"type": "conversation.item.delete",
"item_id": "item_audio_001"
}
Dies ist nützlich, um eine falsche Nachricht zu entfernen oder sicherzustellen, dass der Gesprächsverlauf nicht zu groß wird.
response.create und response.cancel
response.create fordert den Server explizit auf, eine Antwort zu generieren. Im VAD-Modus macht der Server dies eigenständig, sobald er das Ende der Sprache erkennt:
{
"type": "response.create"
}
response.cancel stoppt eine Antwort, die gerade generiert wird. Dies ist nützlich, wenn der Nutzer über den Agenten spricht:
{
"type": "response.cancel"
}
Wichtige Erkenntnisse
- Acht Arten von Ereignissen können vom Client an den Server gesendet werden
session.updatekonfiguriert die Sitzung und kann mehrmals gesendet werdenconversation.item.createermöglicht das Hinzufügen von Text, Verlauf oder Funktionsergebnissenresponse.createist im manuellen Modus erforderlich und im VAD-Modus automatischresponse.cancelermöglicht es Ihnen, den Agenten zu unterbrechen, wenn der Nutzer wieder zu sprechen beginnt