Dominar os eventos WebSocket
Nesta página
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.
| Evento | Finalidade |
|---|---|
session.update | Configura ou reconfigura a sessão (voz, instruções, ferramentas, VAD, formato de áudio) |
input_audio_buffer.append | Envia um fragmento de áudio codificado em base64, continuamente enquanto o utilizador fala |
input_audio_buffer.commit | Confirma o conteúdo atual do buffer como mensagem do utilizador; necessário apenas no modo manual |
input_audio_buffer.clear | Esvazia o buffer de áudio sem o processar |
conversation.item.create | Adiciona um item à conversa: uma mensagem de texto, histórico anterior ou o resultado de uma chamada de função |
conversation.item.delete | Elimina um item da conversa pelo seu ID |
response.create | Solicita ao modelo que gere uma resposta; automático no modo VAD, explícito no modo manual |
response.cancel | Cancela 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.
| Evento | Significado |
|---|---|
session.created | A sessão está aberta |
session.updated | Foi aplicada uma atualização de configuração |
conversation.created | A conversa está configurada |
input_audio_buffer.speech_started | O VAD deteta que o utilizador começou a falar |
input_audio_buffer.speech_stopped | O VAD deteta que o utilizador parou de falar |
input_audio_buffer.committed | O buffer de áudio foi confirmado, pelo VAD ou manualmente |
response.created | Está a ser gerada uma resposta |
response.output_audio.delta | Um fragmento de áudio da resposta, em base64 |
response.output_audio.done | O áudio da resposta está completo |
response.output_audio_transcript.delta | A transcrição textual do áudio, em fluxo contínuo |
response.done | A resposta está completamente terminada |
conversation.item.input_audio_transcription.completed | A transcrição da mensagem do utilizador está disponível |
response.text.delta | Texto em fluxo contínuo, para respostas não vocais |
response.function_call_arguments.delta | Os argumentos de uma chamada de função, em fluxo contínuo |
response.function_call_arguments.done | A chamada de função está completa e pronta para ser executada |
error | Ocorreu 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
commite depoisresponse.createexplicitamente