Resposta rápida
Se um Cloudflare Voice Agent demora para responder ou termina sem áudio, atualize para @cloudflare/voice 0.4.0 com uma versão compatível do Agents SDK e registre o evento turnmetrics. O resumo de cada turno informa o resultado final e os tempos das etapas entre fala, transcrição, modelo, síntese e primeiro áudio.
Não some todos os tempos para calcular o total: a Cloudflare avisa que algumas etapas se sobrepõem. Use o identificador do turno para correlacionar métricas e eventos, descubra a primeira etapa que falhou ou ficou lenta e só então altere modelo, provedor ou conexão.
O que mudou no @cloudflare/voice 0.4.0
Desde 11 de setembro de 2026, cada turno de voz ou texto pode produzir um resumo tipado VoiceTurnMetrics. Ele inclui um turnId, um resultado terminal e medições como fala até transcrição final, início do modelo até primeiro texto, início do TTS até primeiro áudio e duração total do turno.
Antes dessa versão, as quatro métricas agregadas cobriam turnos de fala concluídos e com conteúdo. Elas não explicavam como terminavam turnos abortados, vazios, com falha ou enviados como texto. A mudança permite investigar também esses casos.
Como ativar as métricas de turno
A Cloudflare indica instalar @cloudflare/voice na linha 0.4 e agents na linha 0.22. Depois, no cliente, adicione um listener para turnmetrics e registre apenas os campos necessários. O exemplo oficial lê turn.outcome e turn.turnTotalMs.
Faça a atualização em um branch, gere o lockfile, rode os testes e publique primeiro em homologação. Confirme que servidor e cliente usam versões compatíveis antes de interpretar a ausência do evento como falha da chamada.
- Atualize para @cloudflare/voice@^0.4.0 e agents@^0.22.0.
- Registre um listener de turnmetrics no VoiceClient ou use o resumo fornecido pelo hook React.
- Guarde turnId, outcome e tempos por etapa com o mesmo horário da chamada.
- Teste fala normal, interrupção, silêncio e uma falha controlada em homologação.
- Compare os eventos com logs do servidor e da conexão WebSocket.
Como interpretar um turno sem áudio
Os resultados terminais incluem completed, no_output, output_limit, content_filtered, model_error, tts_error e aborted. Eles apontam a etapa em que a execução terminou, mas não substituem o erro detalhado do provedor nem provam a causa raiz.
Se houver transcrição e primeiro texto, mas não primeiro áudio, concentre a investigação no TTS e na reprodução do cliente. Se nem a transcrição final aparece, verifique permissão do microfone, dispositivo selecionado, captura de áudio e conexão. Se o resultado indicar model_error, consulte a chamada do modelo e seus limites antes de trocar o TTS.
- no_output: confirme se onTurn retornou conteúdo utilizável.
- output_limit: revise o limite atingido e o tamanho da resposta falada.
- content_filtered: confira a política e o conteúdo processado sem registrar dados sensíveis.
- model_error: correlacione com o log da chamada ao modelo.
- tts_error: valide credenciais, provedor de síntese e formato do áudio.
- aborted: verifique interrupção do usuário, cancelamento ou desconexão.
Como localizar onde a latência aumentou
Separe o caminho em quatro partes: microfone até transcrição final, transcrição até primeiro texto do modelo, texto até primeiro áudio do TTS e duração total. Compare cada medida com o histórico da mesma aplicação, região, modelo e provedor. A documentação não define um número universal que transforme um turno em lento.
Uma piora na transcrição pode apontar para áudio, rede ou STT. Atraso antes do primeiro texto concentra a análise no modelo e em ferramentas chamadas por onTurn. Atraso entre texto e áudio direciona a investigação para TTS, tamanho das frases e reprodução. Como há sobreposição, use a sequência dos eventos junto com os tempos.
Diagnóstico local pelo console do navegador
Para depuração local, o withVoice aceita diagnostics com browserConsole habilitado. O console reúne eventos do servidor com sinais do microfone, conexão, modelo, primeiro texto, primeiro áudio e início da reprodução. Essa opção vem desativada por padrão.
Use o console somente em desenvolvimento ou em uma sessão controlada. A Cloudflare informa que nomes e campos desses eventos podem mudar. O SDK remove campos de conteúdo conhecidos, mas mensagens de erro personalizadas ainda podem conter dados sensíveis se a aplicação os incluir.
- Reproduza a falha em uma sessão de desenvolvimento sem dados reais de clientes.
- Confirme se o microfone envia áudio e se o WebSocket permanece conectado.
- Localize o primeiro evento ausente entre transcrição, modelo, TTS e reprodução.
- Correlacione o horário e o turnId com o log do servidor.
- Desative o encaminhamento ao console antes de publicar em produção.
O que testar quando o problema está no navegador
O cliente de voz captura o microfone, transmite áudio e recebe a resposta pelo WebSocket. Uma aplicação pode estar saudável no servidor e ainda ficar muda por permissão negada, entrada errada, saída de som incorreta ou conexão interrompida no navegador.
Teste o microfone e o som fora da aplicação. Depois teste o WebSocket na mesma rede e compare Wi-Fi com rede móvel. Se esses testes passam e o mesmo turnId chega até primeiro áudio, revise a reprodução e o estado da interface. Se a conexão fecha antes, investigue rede, autenticação e os eventos onClose e onError.
Como observar produção sem vazar conversas
Registre tempos, resultado, identificador técnico, versão e provedor, não a fala completa do usuário. Evite enviar transcrições, respostas do modelo, tokens ou mensagens de erro brutas para ferramentas de analytics sem necessidade e base legal.
Os diagnostics channels do Agents SDK produzem eventos estruturados e podem ser encaminhados a um Tail Worker em produção. Eles ajudam a correlacionar conexão e falhas do agente, mas devem seguir retenção, acesso e mascaramento compatíveis com a sensibilidade do serviço.
Limites deste diagnóstico
Este guia foi verificado em 12 de setembro de 2026 nas páginas oficiais da Cloudflare. O pacote de voz está marcado como beta, e a empresa informa que campos dos diagnósticos locais podem mudar. Consulte o changelog e a documentação antes de automatizar alertas baseados nesses nomes.
Uma métrica alta mostra onde o tempo foi gasto, não explica sozinha por que isso ocorreu. Uma página pública também não enxerga o modelo, o provedor de STT ou TTS, as ferramentas chamadas nem os logs internos. A conclusão exige correlação entre cliente, servidor e provedores.
Próxima ação útil
Atualize o pacote em homologação, capture turnmetrics para cinco chamadas representativas e agrupe os resultados por outcome. Comece pela primeira etapa ausente ou mais lenta. Se o navegador nem mantém a sessão, teste microfone, saída de som e WebSocket; se a infraestrutura da Cloudflare apresentar comportamento amplo, confirme o status oficial antes de alterar o código.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Inspect Voice Agent turn latency and outcomesCloudflare Changelog
- VoiceCloudflare Agents Docs
- Voice agent exampleCloudflare Agents Docs
- Diagnostics channelsCloudflare Agents Docs
- WebSocketsCloudflare Agents Docs
- Cloudflare StatusCloudflare