Zdarzenia klient-serwer
Na tej stronie
Wiadomości, które wysyłasz
API Voice Agent działa poprzez wymianę zdarzeń JSON przez WebSocket. W tej lekcji przejdziesz przez każde zdarzenie, jakie Twoja aplikacja może wysłać do serwera. Każde z nich odgrywa konkretną rolę w cyklu konwersacji.
| Zdarzenie | Opis | Kiedy użyć |
|---|---|---|
| session.update | Konfiguracja sesji | Podczas uruchamiania i przy zmianie konfiguracji |
| input_audio_buffer.append | Wysyłanie fragmentu audio w formacie base64 | Ciągle podczas nagrywania |
| input_audio_buffer.commit | Zatwierdzenie bufora audio | W trybie naciśnij-i-mów (push-to-talk) |
| input_audio_buffer.clear | Wyczyszczenie bufora bez przetwarzania | Aby anulować nagrywanie |
| conversation.item.create | Dodanie wiadomości lub wyniku funkcji | Historia, kontekst, wyniki funkcji |
| conversation.item.delete | Usunięcie elementu po ID | Porządkowanie historii konwersacji |
| response.create | Żądanie odpowiedzi | W trybie ręcznym (automatyczne z VAD) |
| response.cancel | Anulowanie trwającej odpowiedzi | Gdy użytkownik przerywa |
conversation.item.create
To zdarzenie pozwala wstrzyknąć wiadomości do konwersacji z pominięciem strumienia audio. Obejmuje trzy główne przypadki.
Dodanie tekstowej wiadomości użytkownika
{
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What's the status of my order 12345?"
}
]
}
}
Wstrzyknięcie historii konwersacji
Przed rozpoczęciem rozmowy głosowej możesz wstępnie wypełnić historię wcześniejszymi wymianami, aby nadać agentowi kontekst:
{
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello, I'm your assistant. How can I help you?"
}
]
}
}
Zwrócenie wyniku funkcji
Po wykonaniu wywołania funkcji odsyłasz wynik za pomocą tego zdarzenia (zob. lekcja 13 dotycząca wywoływania funkcji):
{
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": "call_abc123",
"output": "{\"status\": \"shipped\", \"tracking\": \"FR123456789\"}"
}
}
conversation.item.delete
Usuwa element konwersacji na podstawie jego identyfikatora:
{
"type": "conversation.item.delete",
"item_id": "item_audio_001"
}
Jest to przydatne do usuwania niepoprawnych wiadomości lub zapobiegania nadmiernemu rozrostowi historii konwersacji.
response.create i response.cancel
response.create wyraźnie żąda od serwera wygenerowania odpowiedzi. W trybie VAD serwer robi to samodzielnie po wykryciu końca wypowiedzi:
{
"type": "response.create"
}
response.cancel przerywa generowaną odpowiedź. Przydaje się, gdy użytkownik mówi jednocześnie z agentem:
{
"type": "response.cancel"
}
Kluczowe wnioski
- Możesz wysłać osiem typów zdarzeń z klienta do serwera
session.updatekonfiguruje sesję i można je wysyłać wielokrotnieconversation.item.createpozwala dodać tekst, historię lub wyniki funkcjiresponse.createjest wymagane w trybie ręcznym, a w trybie VAD działa automatycznieresponse.cancelpozwala przerwać działanie agenta, gdy użytkownik ponownie zacznie mówić