Salt la conținutul principal
Română— Alege o limbă
Meniu

Stăpânirea evenimentelor WebSocket

Lecția 4 din 14 Actualizată 29 iulie 2026 Intermediar
Pe această pagină
  1. O conversație compusă din evenimente JSON
  2. Ce trimite aplicația dumneavoastră
  3. Ce trimite serverul înapoi
  4. Scheletul unui client
  5. Partea delicată: întreruperile
  6. Puncte cheie

O conversație compusă din evenimente JSON

În spatele scenei, un schimb vocal cu Voice Agent nu este decât un flux de mesaje JSON care circulă în ambele sensuri prin conexiunea WebSocket. Fiecare mesaj conține un câmp type care indică natura sa. Până nu cunoașteți acest vocabular, clientul dumneavoastră funcționează la noroc. Odată ce îl stăpâniți, știți exact unde să interveniți pentru a întrerupe un răspuns, a afișa o transcriere sau a vă recupera după o eroare.

Evenimentele se împart în două familii, în funcție de direcția lor de deplasare. Cele pe care le trimiteți pilotează sesiunea; cele pe care le primiți vă informează despre ce se întâmplă pe server.

Ce trimite aplicația dumneavoastră

Mesajele dumneavoastră de ieșire acoperă patru nevoi: configurarea sesiunii, alimentarea buffer-ului audio, gestionarea istoricului conversației și controlul generării răspunsurilor.

EvenimentScop
session.updateConfigurează sau reconfigurează sesiunea (voce, instrucțiuni, instrumente, VAD, format audio)
input_audio_buffer.appendTrimite un fragment audio codificat base64, continuu, cât timp utilizatorul vorbește
input_audio_buffer.commitValidează conținutul actual al buffer-ului ca mesaj al utilizatorului; necesar doar în modul manual
input_audio_buffer.clearGolește buffer-ul audio fără a-l procesa
conversation.item.createAdaugă un element la conversație: un mesaj text, un istoric anterior sau rezultatul unui apel de funcție
conversation.item.deleteȘterge un element din conversație după ID-ul său
response.createCere modelului să genereze un răspuns; automat în modul VAD, explicit în modul manual
response.cancelAnulează un răspuns care este în curs de generare

Două dintre aceste mesaje merită o privire mai atentă. conversation.item.create este modul în care injectați contextul: este ceea ce utilizați pentru a restaura istoricul unui apel anterior la începutul unei noi sesiuni. În ceea ce privește input_audio_buffer.clear, acesta este util atunci când utilizatorul nu a spus nimic care să merite procesat (de exemplu, o dregere a glasului captată de un microfon prea sensibil) și preferați să o luați de la capăt cu un buffer curat, decât să lăsați modelul să interpreteze zgomotul.

Ce trimite serverul înapoi

Fluxul de intrare este mai aglomerat, deoarece oferă un comentariu în timp real pentru fiecare etapă de procesare.

EvenimentSemnificație
session.createdSesiunea este deschisă
session.updatedO actualizare de configurare a fost aplicată
conversation.createdConversația este inițializată
input_audio_buffer.speech_startedVAD detectează că utilizatorul a început să vorbească
input_audio_buffer.speech_stoppedVAD detectează că utilizatorul a încetat să vorbească
input_audio_buffer.committedBuffer-ul audio a fost validat, de către VAD sau manual
response.createdUn răspuns este în curs de generare
response.output_audio.deltaUn fragment audio al răspunsului, în base64
response.output_audio.doneAudio-ul răspunsului este complet
response.output_audio_transcript.deltaTranscrierea text a audio-ului, transmisă în flux
response.doneRăspunsul este complet finalizat
conversation.item.input_audio_transcription.completedTranscrierea mesajului utilizatorului este disponibilă
response.text.deltaText transmis în flux, pentru răspunsuri non-vocale
response.function_call_arguments.deltaArgumentele unui apel de funcție, transmise în flux
response.function_call_arguments.doneApelul de funcție este complet și gata de executare
errorA apărut o eroare; majoritatea erorilor sunt recuperabile

Acest ultim eveniment necesită o avertizare. Primirea unui error nu înseamnă că sesiunea este pierdută. Conform documentației de referință xAI, majoritatea erorilor sunt recuperabile și sesiunea rămâne deschisă, astfel încât un client care închide conexiunea la primul error întrerupe o conversație care ar fi putut continua. Înregistrați-l în jurnal, informați utilizatorul dacă este necesar, dar mențineți socket-ul deschis.

Scheletul unui client

În practică, totul se reduce la o structură switch bazată pe msg.type. Iată forma minimă a unui client JavaScript:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // Trimiteți session.update cu configurația
      break;

    case "input_audio_buffer.speech_started":
      // Utilizatorul vorbește: opriți redarea audio a răspunsului
      break;

    case "response.output_audio.delta":
      // Decodați base64 și redați audio-ul
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Executați funcția și trimiteți rezultatul înapoi
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Eroare Voice Agent:", msg.error);
      break;
  }
};

Patru ramuri sunt suficiente pentru a rula un agent: configurați la deschiderea sesiunii, reacționați când utilizatorul începe să vorbească, redați audio-ul primit și executați funcțiile. Celelalte evenimente îmbogățesc interfața și pot aștepta o a doua iterație.

Partea delicată: întreruperile

„Barge-in“, momentul în care utilizatorul începe să vorbească în timp ce agentul răspunde încă, este punctul unde o implementare neglijentă se demască. Serverul anulează singur răspunsul curent și începe să genereze unul nou pe baza a ceea ce tocmai a auzit. Dar, în timp ce serverul a oprit trimiterea, aplicația dumneavoastră deține încă câteva secunde de audio deja primite în buffer-ul de ieșire.

Dacă nu faceți nimic, utilizatorul continuă să audă propoziția pe care tocmai a întrerupt-o în timp ce vorbește peste ea, iar agentul dă impresia că nu ascultă. Așadar, imediat ce primiți speech_started, opriți audio-ul care rulează, goliți buffer-ul de ieșire pentru a nu reda sunete învechite și lăsați serverul să proceseze noua intrare. Acești doi pași necesită câteva linii de cod și fac toată diferența dintre un agent pe care îl puteți întrerupe și unul care vorbește în gol.

Puncte cheie

  • Evenimentele clientului acoperă configurarea, trimiterea audio, gestionarea conversației și controlul răspunsurilor
  • Evenimentele serverului raportează detectarea vorbirii, fragmente audio, transcrieri și apeluri de funcție
  • VAD gestionează automat întreruperile (barge-in)
  • Majoritatea evenimentelor error sunt recuperabile: nu închideți conexiunea, gestionați eroarea
  • În modul manual, trebuie să apelați explicit commit și apoi response.create