Przejdź do głównej treści
Polski— Wybierz język
Menu

Zdarzenia serwer-klient

Lekcja 10 z 16 Zaktualizowano 30 lipca 2026 Programista
Na tej stronie
  1. Otrzymywane wiadomości
  2. Zdarzenia sesji i konwersacji
  3. Zdarzenia bufora audio
  4. Zdarzenia odpowiedzi audio
  5. Zdarzenia transkrypcji
  6. Zdarzenia tekstowe
  7. Zdarzenia wywoływania funkcji
  8. response.done
  9. Zdarzenie błędu
  10. Kluczowe wnioski

Otrzymywane wiadomości

Serwer wysyła wiele zdarzeń, aby informować Cię o stanie konwersacji, dostarczać odpowiedź audio i zgłaszać błędy. Zrozumienie tych zdarzeń jest kluczowe dla budowania responsywnej i niezawodnej aplikacji.

Zdarzenia sesji i konwersacji

Te zdarzenia pojawiają się przy nawiązywaniu połączenia oraz po każdej zmianie konfiguracji:

  • session.created: sesja została otwarta; zdarzenie zawiera konfigurację sesji
  • session.updated: konfiguracja została pomyślnie zaktualizowana
  • conversation.created: kanał konwersacji został skonfigurowany

Zdarzenia bufora audio

Te zdarzenia informują o aktywności głosowej wykrytej przez VAD (wykrywanie mowy):

  • input_audio_buffer.speech_started: VAD wykryło, że użytkownik zaczął mówić
  • input_audio_buffer.speech_stopped: VAD wykryło koniec wypowiedzi
  • input_audio_buffer.committed: bufor audio został zatwierdzony jako wiadomość
ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "input_audio_buffer.speech_started":
      // Użytkownik mówi: pokaż wskaźnik wizualny
      showSpeakingIndicator(true);
      break;

    case "input_audio_buffer.speech_stopped":
      // Użytkownik skończył: ukryj wskaźnik
      showSpeakingIndicator(false);
      break;

    case "input_audio_buffer.committed":
      // Wiadomość audio jest przetwarzana
      showProcessingIndicator(true);
      break;
  }
});

Zdarzenia odpowiedzi audio

Strumień audio odpowiedzi jest przesyłany za pomocą dwóch zdarzeń.

response.output_audio.delta

Każdy delta zawiera fragment audio zakodowany w formacie base64. Zbierz je i odtwórz w odpowiedniej kolejności:

{
  "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

Sygnalizuje, że całe audio odpowiedzi zostało wysłane:

{
  "type": "response.output_audio.done",
  "item_id": "item_resp_001"
}

Zdarzenia transkrypcji

API potrafi transkrybować zarówno audio użytkownika, jak i audio odpowiedzi:

  • conversation.item.input_audio_transcription.completed: transkrypcja tego, co powiedział użytkownik
  • response.output_audio_transcript.delta: strumieniowa transkrypcja odpowiedzi agenta
case "conversation.item.input_audio_transcription.completed":
  console.log("Użytkownik powiedział:", event.transcript);
  displayUserMessage(event.transcript);
  break;

case "response.output_audio_transcript.delta":
  appendAgentTranscript(event.delta);
  break;

Zdarzenia tekstowe

Jeśli agent generuje tekst (dodatkowo do audio lub zamiast niego), otrzymasz:

  • response.text.delta: strumieniowy fragment tekstu
{
  "type": "response.text.delta",
  "delta": "Twoje zamówienie zostało"
}

Zdarzenia wywoływania funkcji

Gdy agent zdecyduje się wywołać funkcję, emitowane są dwa zdarzenia:

  • response.function_call_arguments.delta: argumenty funkcji, przesyłane strumieniowo
  • response.function_call_arguments.done: kompletne wywołanie funkcji ze wszystkimi jej argumentami

Lekcja 13, dotycząca wywoływania funkcji głosowych, szczegółowo omawia te zdarzenia.

response.done

To zdarzenie oznacza całkowite zakończenie odpowiedzi. Zawiera podsumowanie odpowiedzi, w tym statystyki użycia:

{
  "type": "response.done",
  "response": {
    "id": "resp_001",
    "status": "completed",
    "output": [...]
  }
}

Zdarzenie błędu

To zdarzenie zgłasza błędy. Zgodnie z dokumentacją referencyjną xAI, większość błędów można naprawić, a połączenie WebSocket pozostaje otwarte:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Określono nieprawidłowy format audio"
  }
}

Twoja aplikacja powinna logować te błędy i, w zależności od ich wagi, wyświetlić użytkownikowi komunikat lub spróbować automatycznie naprawić problem.

Kluczowe wnioski

  • Serwer wysyła zdarzenia dla każdego etapu: wykrywanie głosu, audio, transkrypcja, tekst i błędy
  • Audio odpowiedzi przychodzi jako fragmenty base64 przez response.output_audio.delta
  • Transkrypcje są dostępne zarówno dla danych wejściowych użytkownika, jak i wyjściowych agenta
  • response.done oznacza koniec kompletnej odpowiedzi
  • Większość błędów zgłaszanych przez zdarzenie error można naprawić: połączenie pozostaje otwarte