Construir streaming robusto para chatbot de IA: Reconexão, respostas parciais e status acessíveis

O streaming faz um chatbot de IA parecer mais rápido porque as primeiras palavras aparecem antes da resposta completa ser calculada. Tecnicamente, porém, isso cria um fluxo distribuído: servidor, provedor do modelo, proxy, navegador e interface do usuário mantêm o estado juntos por segundos ou minutos. As redes móveis mudam, uma aba vai para o segundo plano, um proxy encerra uma conexão inativa ou o usuário envia a mensagem novamente por engano. Sem um protocolo claro, partes do texto são exibidas em duplicado, afirmações incompletas são marcadas como concluídas ou a mesma ação de ferramenta é acionada duas vezes.

Um chatbot de site robusto trata o streaming como uma máquina de estados, não como uma animação. Este guia mostra como IDs de evento, retomada, conclusão atômica e mensagens discretas para leitor de tela funcionam em conjunto.

Uma mensagem precisa de uma identidade permanente

Atribua um ID de solicitação do lado do cliente ao enviar e um ID de mensagem imutável do lado do servidor. Cada seção do stream também recebe um número de sequência incremental. Se o mesmo pedido chegar novamente após um erro de conexão, o servidor não deve iniciar uma segunda execução independente, mas sim retornar o estado existente ou continuar com segurança.

As identidades cumprem papéis diferentes: o ID da solicitação torna a operação de escrita idempotente, o ID da mensagem identifica o resultado e o número de sequência ordena os fragmentos. Um carimbo de data/hora isolado não basta, pois solicitações paralelas podem colidir ou chegar com atraso.

Separar transporte e estado de negócio

Quer se usem Server-Sent Events, Fetch Streams ou WebSockets, o ciclo de vida de negócio não muda. Modele pelo menos os estados aceito, em execução, concluído, cancelado e com falha. Apenas um evento de conclusão explícito torna uma resposta vinculativa. Por outro lado, o fim de uma conexão TCP não significa sucesso automático.

Para Server-Sent Events, o padrão HTML descreve reconexões e o envio do último ID de evento. Essa mecânica é útil, mas não substitui um histórico no servidor. O servidor precisa saber quais fragmentos pertencem a uma mensagem e se uma nova busca pode ignorar sequências já enviadas.

Reconexão sem texto duplicado

Armazene um buffer de eventos limitado para cada mensagem em andamento. Ao reconectar, o cliente envia a última sequência confirmada. O servidor entrega apenas eventos posteriores. Se o buffer tiver expirado, em vez de responder com fragmentos presumidos, ele envia um snapshot do texto completo atual e uma nova sequência base.

O cliente processa os eventos de forma idempotente: sequências menores ou iguais ao último valor aplicado são ignoradas. Lacunas maiores acionam a busca de um snapshot. Isso mantém a exibição correta, mesmo se um proxy repetir dados ou o navegador retornar após um curto período offline.

Respostas parciais não podem acionar ações

O texto transmitido via streaming é provisório. Links podem estar incompletos, uma restrição pode surgir apenas na frase seguinte e argumentos estruturados de ferramentas são sintaticamente inválidos até o fim. Renderize o texto progressivamente, mas ative ações de risco apenas após a conclusão e uma validação separada.

Isso se aplica especialmente a pedidos, agendamentos, alterações em dados de clientes ou envio de e-mails. A execução de uma ferramenta precisa de seu próprio ID de ação idempotente, verificação de permissão e, se necessário, uma confirmação visível. Uma reconexão nunca deve executar o mesmo efeito novamente.

Tratar o cancelamento como um evento de protocolo real

Um botão de parar não deve apenas pausar a exibição. O cliente envia uma solicitação de cancelamento com o ID da mensagem; o servidor marca a execução e, se possível, encerra o trabalho do modelo e das ferramentas. Fragmentos que chegarem posteriormente são descartados. Na interface, permanece visível que a resposta foi cancelada.

Se o cancelamento não atingir o servidor, o trabalho pode continuar lá. Por isso, o servidor também verifica o status regularmente. As métricas de custo e latência devem contar execuções canceladas separadamente, caso contrário, parecerão erros normais ou desaparecerão completamente da análise.

Tornar os erros compreensíveis e repetíveis

Diferencie pelo menos entre interrupção de rede, tempo limite (timeout), erro de provedor, bloqueio de segurança e validação de negócio. A mensagem para o usuário não precisa expor a tecnologia interna, mas deve indicar o próximo passo seguro. "Conexão interrompida – a resposta será retomada" é diferente de "Esta ação não foi executada".

Um botão de tentar novamente só reutiliza o ID de solicitação original se a mesma execução for ser continuada. Para uma regeração real, um novo ID é criado e a interface não mostra ambas as versões como um único resultado.

Não sobrecarregar o leitor de tela com cada token

O conteúdo dinâmico precisa ser perceptível por tecnologias assistivas. O WAI-ARIA define Live Regions e diferentes níveis de urgência para isso. Uma região atualizada token por token com aria-live pode gerar centenas de interrupções. É melhor usar um indicador visual de streaming com um canal de status cortês e separado.

Informe, por exemplo, "A resposta está sendo gerada", depois, em intervalos adequados, uma frase ou seção concluída e, no final, "Resposta completa". Use aria-live="polite" para progressos normais; assertive é adequado apenas para erros realmente urgentes. O foco permanece no campo de entrada ou no local escolhido pelo usuário e não salta a cada fragmento.

Defina aria-busy="true" na área de resposta enquanto o conteúdo estiver incompleto e remova-o após a conclusão atômica. O botão de parar precisa de um nome claro e deve ser acessível via teclado. Além disso, verifique suporte a movimento reduzido, zoom e exibições em telas móveis pequenas.

Testar a máquina de estados de forma direcionada

Um teste de caminho feliz (happy path) não é suficiente. Automatize pelo menos estes casos:

• Desconectar após vários fragmentos e retomar sem duplicar texto.
• Entregar o mesmo evento duas vezes e aplicá-lo apenas uma vez.
• Omitir uma sequência e solicitar um snapshot.
• Pausar a aba, trocar de rede e depois exibir a conclusão correta.
• Cancelar durante a preparação de uma ferramenta e não executar nenhum efeito.
• Marcar como incompleto após timeout com resposta parcial visível.
• Verificar se os avisos do leitor de tela têm frequência adequada e comportamento correto de foco.

Acompanhe o tempo até a primeira seção visível, tempo até a conclusão total, taxa de reconexão, sequências duplicadas ou descartadas e sucesso no cancelamento. O tempo até o primeiro token isoladamente pode parecer bom, mesmo que muitas respostas nunca sejam concluídas com confiabilidade.

Um plano de implementação em etapas

1. Definir estados de mensagens e eventos do lado do servidor.
2. Implementar IDs idempotentes e sequências antes da animação da interface.
3. Adicionar reconexão com buffer e fallback para snapshot.
4. Separar estritamente ações de ferramentas do texto provisório.
5. Verificar mensagens de status com teclado e leitor de tela.
6. Testar casos de erro em redes limitadas e instáveis.
7. Somente depois ativar o streaming gradualmente para o tráfego de produção.

Conclusão: Rápido de visualizar, claramente concluído

Um bom streaming combina velocidade percebida com um modelo de consistência claro. IDs permanentes, eventos ordenados, uma conclusão atômica e uma reconexão segura evitam respostas duplicadas ou pela metade. Uma Live Region discreta torna o processo acessível sem interromper usuários de leitores de tela a cada token.

Em seguida, teste um chat real em uma rede móvel instável. Se, após o cancelamento e a reconexão, não estiver claro qual mensagem está completa e qual ação foi realmente executada, o protocolo precisa de reparo primeiro — não a animação de carregamento.

Fontes

• WHATWG HTML Standard: Server-Sent Events
• MDN Web Docs: Streams API
• W3C: WAI-ARIA 1.2
• W3C WAI: Mensagens de status com ARIA Live Regions