💡 Como ler este módulo
Abra o frontend do DeerFlow em outra aba enquanto lê. Cada tópico aponta um elemento concreto da UI — é infinitamente mais rápido achar se você fizer o tour com a tela ligada do que tentar decorar nomes de painéis.
🗺️ Tour pelo frontend Next.js
O frontend é uma aplicação Next.js que roda no container Docker junto do backend. É uma UI enxuta: barra lateral de sessões, painel principal de conversa, painel de traces e barra superior com os controles de modo. Nada exótico — mas saber onde cada coisa mora elimina metade das perguntas operacionais que surgem na semana 1.
🎯 Os quatro painéis que importam
- Sessões— lateral esquerda. Lista persistente. Cada sessão guarda histórico completo e tem configuração independente.
- Conversa— centro. Messages streaming, upload, botão de cancelar. É 80% do tempo de tela.
- Traces— lateral direita, expansível. Cada passo do agente com tokens e tempo. Abra quando quiser entender o porquê.
- Controles— barra superior. Toggles de plan mode, thinking, skill forçada, provider por sessão.
💡 Config por sessão
Cada sessão tem seu próprio provider, skills ativas e toggles. Isso significa que você pode ter uma sessão "barata" com gpt-4o-mini para rascunho e outra "premium" com Claude Sonnet + thinking para revisão final — lado a lado, sem conflito.
🔁 Anatomia de uma conversa
Cada turno do DeerFlow segue o mesmo ciclo canônico. Saber enxergá-lo no trace é a diferença entre "o agente está falhando" e "o agente está falhando nesta etapa específica". Com o segundo, você sabe onde intervir.
Prompt do usuário
A mensagem entra pelo frontend, é anexada ao histórico da sessão e passa por um pré-processamento leve (deduplicar system prompt, resolver variáveis). Ainda não chegou no modelo.
Lead agent planeja
O lead_agent recebe o prompt + as descrições de todas as skills ativas e decide: é pergunta direta? precisa de skill? qual? em que ordem? Se plan mode está ligado, ele emite um plano escrito antes de executar.
Execução
Skills são acionadas, sub-agents são invocados, tools são chamadas (search, sandbox, memória). Cada passo vira um nó no grafo LangGraph. O trace registra tudo.
Síntese
O lead_agent recebe os resultados dos passos, escreve a resposta final e inicia o streaming para o frontend. O usuário começa a ler enquanto o texto ainda está sendo gerado.
Persistência
Histórico é salvo. Fatos novos podem ir para a memória de longo prazo. Trace é guardado. Se LangSmith/Langfuse está ativo, é exportado.
📋 Plan mode — aprovar antes de executar
Plan mode insere um passo de revisão entre planejamento e execução. O agente escreve o plano em português, você lê, aprova, edita ou rejeita. Só depois ele executa. É o controle mais importante para tarefas caras ou irreversíveis — e é o melhor jeito didático de ver como o agente está pensando.
🎯 O que plan mode entrega
Um plano estruturado (3–8 passos em texto) que você pode editar inline antes de dar "ok". Edição inline é literal: apague um passo, adicione instrução, reordene, mude um parâmetro. A versão editada é o que o lead_agent executa.
- •Controle por turno, não por sessão — você liga e desliga no botão
- •Adiciona ~10-30 segundos ao turno (um round-trip a mais)
- •Ótimo para research longa, ações com efeito colateral, debug de comportamento
✓ Ligar quando
- ✓Pesquisa vai custar muitos tokens
- ✓Ação tem efeito colateral (escrever arquivo, fazer deploy)
- ✓Você está debugando por que a última resposta veio errada
- ✓Quer ensinar/mostrar como o agente raciocina
✗ Desligar quando
- ✗Perguntas rápidas que cabem em um único turno
- ✗Fluxo de conversa rápida onde latência mata
- ✗Você não tem intenção de ler o plano
- ✗Uso em demo com audiência impaciente
💭 Thinking mode — quando vale o custo
Thinking mode libera o modelo para raciocinar antes de responder — mais tokens, mais tempo, geralmente respostas muito melhores em tarefas complexas. É o mesmo princípio por trás de o1, Claude Sonnet extended thinking, Gemini 2.5 Thinking. O que muda é que no DeerFlow você escolhe turno a turno, não precisa trocar de modelo.
📊 Tokens vs qualidade
- ~3-8× — aumento típico de tokens consumidos por turno com thinking ligado
- ~30-200% — melhoria de qualidade em tarefas de raciocínio, análise, debug, matemática
- ~0% — melhoria em fatos diretos, reformulações, sumarizações simples
- Regra — se a pergunta cabe numa única frase de resposta, thinking é desperdício
🎯 Casos onde thinking brilha
- •Debug — "por que este código retorna None quando deveria retornar 5"
- •Matemática aplicada — modelagem, dimensionamento, otimização
- •Análise crítica — comparar abordagens, encontrar a falha num argumento
- •Planejamento multi-passo — onde cada passo afeta os próximos
💡 Dica prática
Thinking não é retry. Se a primeira resposta veio errada, ligar thinking e reenviar pode ajudar — mas pode também dar a mesma resposta com mais confiança. Se o problema é de contexto faltante (memória, arquivo, prompt ambíguo), thinking não corrige. Primeiro conserte a entrada, depois considere ligar thinking.
🌊 Streaming de respostas
O DeerFlow stream-a tudo: tokens da resposta, entradas do trace, sub-steps de skills. Você lê enquanto o agente gera. Isso não é só confort visual — é uma ferramenta ativa: se você vê que a resposta está indo para o lado errado nas primeiras frases, aperta o botão de cancelar e economiza tempo e tokens.
🎯 O que flui em streaming
- •Tokens da resposta — o texto principal, chunk por chunk
- •Eventos do trace — "skill X acionada", "sub-agent Y iniciado"
- •Status de tool calls — pending, running, done, error
- •Contadores — tokens consumidos, tempo decorrido
💡 Interromper economiza 30-40%
Nas tarefas longas, uma fração significativa termina com você percebendo nas primeiras frases que o agente entendeu errado. Cancelar cedo, refinar o prompt e reenviar é sempre mais barato do que esperar o final e pedir correção. Treine o reflexo de ler os primeiros chunks com atenção.
🧪 Lab: plan + thinking lado a lado
Teoria sobre modos é insuficiente. Sentir na pele a diferença entre as quatro combinações (plan on/off × thinking on/off) numa pergunta média é a única forma de construir a regra pessoal que vai te guiar depois.
🎯 O que você vai fazer
Escolher uma pergunta de dificuldade média, rodar as quatro combinações, anotar tempo + tokens + qualidade subjetiva, e escrever a sua heurística para quando ligar cada modo.
📊 Por que esse lab
Os modos são os controles mais impactantes do DeerFlow e os mais subutilizados. A maioria liga plan mode "por segurança" e thinking "porque parece bom" — desperdiçando minutos e tokens. Outros não ligam nunca e acham que o agente é mediano. Um único lab comparativo resolve os dois extremos.
Escolha a pergunta
Evite perguntas triviais ("capital do Brasil") e perguntas gigantes ("pesquise tudo sobre LLMs"). Alvo: algo que precise de 2-4 passos de raciocínio. Exemplo: "Compare 3 abordagens de RAG híbrido considerando custo de indexação e latência de inferência."
Rode as 4 variantes
Use 4 sessões separadas (para não poluir histórico). Em cada uma, configure: (A) plan off / thinking off, (B) plan on / thinking off, (C) plan off / thinking on, (D) plan on / thinking on. Mesma pergunta nas quatro.
Anote as métricas
Para cada variante: tempo total, tokens totais (o trace mostra), e uma nota subjetiva de 1–5 para qualidade. Seja honesto — é comum a variante A já ser suficiente.
Escreva sua regra
Uma frase, máximo duas: "Eu ligo plan quando X. Eu ligo thinking quando Y." Essa regra pessoal, baseada no que você viu, vale mais que qualquer recomendação genérica.
📝 Resumo do Módulo
Próximo Módulo:
1.4 — 🎯 Skills — a capacidade principal
Catálogo público, como invocar manualmente e como o agente decide sozinho qual usar.