Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Dominar os eventos WebSocket

Aula 4 de 14 Atualizada a 29 de julho de 2026 Intermediario
Nesta página
  1. Uma conversa composta por eventos JSON
  2. O que a sua aplicação envia
  3. O que o servidor devolve
  4. A estrutura de um cliente
  5. A parte delicada: interrupções
  6. Pontos-chave

Uma conversa composta por eventos JSON

Nos bastidores, uma troca de voz com o Agente de Voz é apenas um fluxo de mensagens JSON que circula nos dois sentidos através da ligação WebSocket. Cada mensagem possui um campo type que indica o que ela é. Enquanto não dominar este vocabulário, o seu cliente funciona à sorte. Assim que o fizer, saberá exatamente onde intervir para interromper uma resposta, apresentar uma transcrição ou recuperar de um erro.

Os eventos dividem-se em duas famílias, consoante a direção do seu tráfego. Os que envia conduzem a sessão; os que recebe informam-no sobre o que está a acontecer no servidor.

O que a sua aplicação envia

As suas mensagens de saída cobrem quatro necessidades: configurar a sessão, alimentar o buffer de áudio, gerir o histórico da conversa e controlar a geração de respostas.

EventoFinalidade
session.updateConfigura ou reconfigura a sessão (voz, instruções, ferramentas, VAD, formato de áudio)
input_audio_buffer.appendEnvia um fragmento de áudio codificado em base64, continuamente enquanto o utilizador fala
input_audio_buffer.commitConfirma o conteúdo atual do buffer como mensagem do utilizador; necessário apenas no modo manual
input_audio_buffer.clearEsvazia o buffer de áudio sem o processar
conversation.item.createAdiciona um item à conversa: uma mensagem de texto, histórico anterior ou o resultado de uma chamada de função
conversation.item.deleteElimina um item da conversa pelo seu ID
response.createSolicita ao modelo que gere uma resposta; automático no modo VAD, explícito no modo manual
response.cancelCancela uma resposta que está a ser gerada

Duas destas mensagens merecem uma análise mais atenta. conversation.item.create é a forma de injetar contexto: é o que utiliza para restaurar o histórico de uma chamada anterior no início de uma nova sessão. Quanto a input_audio_buffer.clear, é útil quando o utilizador claramente não disse nada que valesse a pena processar (um pigarro captado por um microfone demasiado sensível) e prefere recomeçar com um buffer limpo em vez de deixar o modelo interpretar ruído.

O que o servidor devolve

O fluxo de entrada é mais intenso, pois fornece um comentário contínuo sobre cada etapa do processamento.

EventoSignificado
session.createdA sessão está aberta
session.updatedFoi aplicada uma atualização de configuração
conversation.createdA conversa está configurada
input_audio_buffer.speech_startedO VAD deteta que o utilizador começou a falar
input_audio_buffer.speech_stoppedO VAD deteta que o utilizador parou de falar
input_audio_buffer.committedO buffer de áudio foi confirmado, pelo VAD ou manualmente
response.createdEstá a ser gerada uma resposta
response.output_audio.deltaUm fragmento de áudio da resposta, em base64
response.output_audio.doneO áudio da resposta está completo
response.output_audio_transcript.deltaA transcrição textual do áudio, em fluxo contínuo
response.doneA resposta está completamente terminada
conversation.item.input_audio_transcription.completedA transcrição da mensagem do utilizador está disponível
response.text.deltaTexto em fluxo contínuo, para respostas não vocais
response.function_call_arguments.deltaOs argumentos de uma chamada de função, em fluxo contínuo
response.function_call_arguments.doneA chamada de função está completa e pronta para ser executada
errorOcorreu um erro; a maioria dos erros é recuperável

Este último requer um aviso. Receber error não significa que a sessão se perdeu. De acordo com a referência da xAI, a maioria dos erros é recuperável e a sessão permanece aberta, pelo que um cliente que feche a ligação ao primeiro error interrompe uma conversa que poderia ter continuado. Registe-o, informe o utilizador se necessário, mas mantenha o socket aberto.

A estrutura de um cliente

Na prática, tudo se resume a um switch sobre msg.type. Eis a forma mínima de um cliente JavaScript:

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

  switch (msg.type) {
    case "session.created":
      // Enviar session.update com a configuração
      break;

    case "input_audio_buffer.speech_started":
      // O utilizador está a falar: parar o áudio da resposta que está a ser reproduzido
      break;

    case "response.output_audio.delta":
      // Descodificar o base64 e reproduzir o áudio
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Executar a função e enviar o resultado de volta
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Erro do Agente de Voz:", msg.error);
      break;
  }
};

Quatro ramos são suficientes para executar um agente: configurar quando a sessão abre, reagir quando o utilizador começa a falar, reproduzir o áudio recebido e executar funções. Os outros eventos enriquecem a interface e podem esperar por uma segunda iteração.

A parte delicada: interrupções

O “barge-in”, quando o utilizador começa a falar enquanto o agente ainda está a responder, é onde uma implementação descuidada falha. O servidor cancela a resposta atual por conta própria e começa a gerar uma nova com base no que acabou de ouvir. Mas, enquanto o servidor parou de enviar, a sua aplicação ainda mantém vários segundos de áudio já recebido no seu buffer de saída.

Se não fizer nada, o utilizador continua a ouvir a frase que acabou de interromper enquanto fala por cima dela, e o agente parece não estar a ouvir. Assim, assim que receber speech_started, pare o áudio que está a ser reproduzido, limpe o buffer de saída para não reproduzir som desatualizado e deixe o servidor processar a nova entrada. Estes dois passos levam algumas linhas de código e fazem toda a diferença entre um agente que pode ser interrompido e um que fala para o vazio.

Pontos-chave

  • Os eventos do cliente cobrem configuração, envio de áudio, gestão da conversa e controlo de respostas
  • Os eventos do servidor reportam deteção de fala, fragmentos de áudio, transcrições e chamadas de função
  • O VAD gere as interrupções (barge-in) automaticamente
  • A maioria dos eventos error é recuperável: não feche a ligação, trate o erro
  • No modo manual, deve chamar commit e depois response.create explicitamente