Pular para o conteúdo principal
O ChatCLI suporta streaming em tempo real de respostas de LLM, exibindo o texto character-by-character conforme ele e gerado pela API. Isso melhora significativamente a experiencia do usuario, eliminando a espera por respostas completas.

​
Interface StreamingClient

O streaming e implementado como uma interface opcional que provedores podem adotar: 
type StreamingClient interface {
    LLMClient

    SendPromptStream(ctx context.Context, prompt string,
        history []models.Message, maxTokens int) (<-chan StreamChunk, error)

    SupportsStreaming() bool
}
A deteccao e automatica via type assertion — provedores que implementam StreamingClient recebem streaming automaticamente: 
if sc, ok := client.AsStreamingClient(c); ok {
    chunks, err := sc.SendPromptStream(ctx, prompt, history, maxTokens)
    // processa chunks em tempo real
}
Provedores que nao implementam StreamingClient continuam funcionando normalmente. O ChatCLI faz fallback para SendPrompt (resposta completa) automaticamente.

​
StreamChunk

Cada chunk do streaming carrega:
CampoTipoDescricao
TextstringTexto incremental neste chunk (pode ser vazio)
Donebooltrue no chunk final
Usage*UsageInfoDados de uso de tokens (apenas no chunk final)
StopReasonstringRazao da parada: end_turn, max_tokens, tool_use
ErrorerrorErro durante streaming (termina o stream)

​
Contrato de Streaming

  • O canal retorna zero ou mais chunks de texto
  • O chunk final tem Done=true e pode incluir Usage e StopReason
  • Se ocorrer erro, um chunk com Error e enviado e o canal fecha
  • O canal fecha apos o chunk final ou erro
  • O caller pode cancelar via contexto

​
Provedores com Suporte

ProvedorStreamingObservacoes
Anthropic (API Key)SimStreaming nativo via Messages API
Anthropic (OAuth)SimStreaming via token OAuth
OpenAISimStreaming via Chat Completions
ZAI (Zhipu AI)SimStreaming compativel com OpenAI
MiniMaxSimStreaming compativel com OpenAI
OpenRouterSimStreaming via API OpenAI-compatible
Google (Gemini)NaoFallback para resposta completa
xAI (Grok)NaoFallback para resposta completa
GitHub ModelsNaoFallback para resposta completa
OllamaNaoFallback para resposta completa

​
Stream Watchdog

O Stream Watchdog monitora o stream para detectar stalls (interupcoes sem dados) e prevenir que o ChatCLI fique travado esperando indefinidamente:
TimerDuracaoAcao
Warning45 segundosLoga aviso de stall no log
Idle Timeout90 segundosAborta stream e retorna conteudo parcial
Ambos os timers sao resetados a cada chunk recebido. Se o provedor parar de enviar dados por 90 segundos, o watchdog interrompe o stream e retorna o texto ja acumulado.

​
Configuracao do Watchdog

Variavel de AmbienteDescricaoDefault
CHATCLI_STREAM_IDLE_TIMEOUT_SECONDSTimeout de idle em segundos90
Em redes lentas ou com provedores que tem alta latencia entre chunks, aumente o timeout para evitar interrupcoes prematuras. O padrao de 90 segundos e suficiente para a maioria dos cenarios.

​
Fallback para Nao-Streaming

Quando o streaming nao esta disponivel (provedor nao suporta ou erro na conexao), o ChatCLI faz fallback automatico: 
1. Tenta SendPromptStream()  → streaming em tempo real
2. Se nao suportado → fallback para SendPrompt()
3. Resposta completa exibida de uma vez
A funcao DrainStream permite converter um stream em resposta completa quando necessario: 
text, usage, stopReason, err := client.DrainStream(chunks)

​
Integracao com TUI

No modo interativo (Bubble Tea), o streaming integra-se diretamente com o renderizador:
  • Cada chunk e emitido como evento via TUIEmitter
  • O modelo Bubble Tea atualiza a view incrementalmente
  • Markdown e renderizado progressivamente via Glamour
  • A barra de status mostra o estado do streaming em tempo real
No modo one-shot (-p), o streaming e desabilitado e DrainStream e usado para coletar a resposta completa antes de imprimir.

​
Proximos Passos

Recuperacao de Contexto

O que acontece quando max_tokens e atingido durante streaming.

Provider Fallback

Chain de fallback entre provedores com e sem streaming.

Tool Use Nativo

Streaming com tool calls nativas.

UI de Progresso

Indicadores visuais durante streaming do agente.