🌱 Fundamentos

Um harness que orquestra sub-agents, memória e sandboxes por meio de skills extensíveis — é a camada entre o LLM e tudo que ele precisa fazer.

Quem confunde harness com framework acaba reescrevendo coisas prontas. Quem confunde com chatbot subestima o que um harness resolve.

Harness = orquestrador; skills = capacidades plugáveis; sandbox = execução isolada; sub-agents = delegação controlada.

A v2 é uma reescrita completa. Não compartilha código com a v1, que era focada em Deep Research. A v2 é um harness de uso geral.

Muita documentação antiga ainda circula. Saber diferenciar evita procurar coisas no lugar errado e aplicar padrões obsoletos.

v1 = pipeline fixo; v2 = grafo LangGraph + skills; não há migração automática; ambos coexistem no ecossistema.

Unidades de capacidade que o agente aciona quando o contexto bate. Cada skill tem um escopo, um prompt e (opcionalmente) tools próprias.

Skills são o principal ponto de extensão. Entender o contrato de uma skill é pré-requisito para usar o DeerFlow fora do mínimo.

Trigger accuracy (descrição clara); auto-seleção pelo lead_agent; catálogo público maduro; criação via meta-skill skill-creator.

Agentes filhos que o agente principal invoca para fazer um pedaço da tarefa com contexto isolado e retornar só o resultado útil.

Sub-agents protegem a janela de contexto do agente principal. Sem eles, pesquisas longas contaminam o contexto com lixo intermediário.

Isolamento de contexto; retorno resumido; diferente de custom agent; essencial para research e refatorações longas.

O ambiente onde código gerado pelo agente roda. Três modos: Local, Docker e Kubernetes — cada um com trade-off entre conveniência e segurança.

Rodar script gerado por LLM no host é como executar email attachment. O modo de sandbox é uma decisão de risco, não de performance.

Local = rápido, perigoso; Docker = default razoável; K8s = produção e multi-tenant; imagem customizável; quotas de recurso.

O conjunto de técnicas que decidem o que entra e o que sai da janela de contexto em cada turno do agente.

O que faz o agente parecer "burro" quase sempre é contexto mal gerido, não modelo fraco. Entender isso derruba 80% das frustrações.

Compactação automática; summarization de histórico; prioridade de memórias; perda silenciosa quando a janela enche.

Armazenamento de longo prazo que sobrevive a conversas. Guarda perfil do usuário, preferências, fatos do projeto e referências externas.

Memória mal usada vira memory poisoning. Memória bem usada transforma o agente em colaborador contínuo em vez de assistente amnésico.

Memória é primeira classe na v2; você revisa e edita; índice semântico; distinção entre memória e histórico de sessão.

Panorama dos domínios que o DeerFlow cobre bem com skills prontas: deep research, relatórios, code review, newsletters, PPTs, podcasts, análise de dados.

Entender o leque de casos evita reinventar. Em muitas situações existe skill pronta que resolve 80% do problema.

Catálogo maduro cobre mídia, análise, engenharia e pesquisa; combinação de skills é o padrão; saber quando não usar também importa.

Dois caminhos de configuração: make setup é um wizard interativo; make config deixa você editar os arquivos na mão.

O wizard economiza tempo na primeira vez, mas esconde onde as coisas moram. Entender os dois evita ficar dependente do caminho fácil.

Setup = amigável; config = explícito; ambos geram os mesmos arquivos finais; você pode começar num e terminar no outro.

config.yaml guarda decisões estruturais (providers, sandbox, skills). .env guarda segredos (API keys, tokens). Nunca misture os dois.

Errar a divisão é o atalho mais rápido para vazar chave em git. E torna a config não-reproduzível para outro ambiente.

config.yaml versionável; .env no .gitignore; substituição de variáveis no YAML; ordem de precedência entre os dois.

Você liga o DeerFlow a um ou mais LLMs via provider: OpenAI, OpenRouter, Claude Code OAuth, Codex CLI, vLLM local, Doubao, DeepSeek, Kimi.

A escolha de provider muda custo, latência, qualidade e privacidade. Não há resposta universal — depende do seu caso de uso.

Multi-provider de primeira classe; cada skill pode fixar um modelo preferido; local roda via vLLM; CLI-backed para quem tem assinatura.

Comando de diagnóstico que valida config, pinga providers, checa dependências do sandbox e reporta erros com sugestão de fix.

90% dos problemas de primeira instalação já têm detecção pronta no doctor. Rodar antes de pedir ajuda é educação mínima.

Rode após qualquer mudança de config; saída machine-readable; parte do fluxo de CI recomendado.

O DeerFlow tem alvos make para Docker: make docker-init e make docker-start, que isolam o sandbox e o frontend.

Docker é o default que equilibra conveniência e segurança. Evita poluir o host e é fácil de resetar quando quebra.

Imagem base estável; volumes para memória e skills; reset com docker-clean; não é ainda produção multi-tenant.

Subir via Docker, abrir o frontend e rodar uma pergunta real — sem ser "diga oi", mas algo que exercite uma skill.

Sair do "hello world" na primeira execução força você a ver o loop plan → execute → resultado sem achar que é mágica.

docker-init; docker-start; abrir localhost; prompt de pesquisa curta; inspecionar traces; comparar resposta com/sem skill.

Uma UI web em Next.js que conversa com o backend, mostra traces, permite upload de arquivos e configura por sessão.

Achar rápido onde mora plan, thinking, memória e traces elimina metade das dúvidas operacionais.

Layout em painéis; painel de traces; botões de modo; histórico persistente por sessão.

O ciclo canônico: prompt do usuário → o lead_agent planeja → executa passos via skills/tools → devolve o resultado final.

Entender o ciclo te dá intuição para saber onde intervir: refinar prompt, forçar skill, revisar plano, ou aceitar.

Lead agent; planejamento opcional; execução em streaming; resultado auditável via trace.

Um modo em que o agente propõe um plano escrito antes de executar, e você aprova, edita ou rejeita.

Plan mode é o principal controle para tarefas caras ou irreversíveis. Também é a melhor ferramenta didática — te mostra como o agente está pensando.

Opcional por turno; edita o plano inline; útil para research e ações com efeito colateral; aumenta latência.

Modo que libera o modelo para raciocinar antes de responder. Mais tempo, mais tokens, respostas geralmente melhores em tarefas complexas.

Ligar thinking em perguntas simples é desperdício; desligar em problemas duros é ilusão de velocidade com resultado pior.

Não é retry; custa tokens extras; ótimo para debug, matemática, análise; inútil para fato direto.

A resposta chega em chunks, permitindo que você comece a ler e interrompa se estiver indo por um caminho errado.

Interromper cedo economiza tempo e tokens em 30-40% das tarefas longas — se você souber reconhecer que está errado.

Tokens em tempo real; botão de cancelar; trace também flui; não quebra auditoria.

Rodar a mesma pergunta em 4 combinações (plan on/off × thinking on/off) e comparar tempo, custo e qualidade.

Sentir na pele a diferença evita que você use os modos por reflexo — vai entender quando cada um vale a pena.

Escolher pergunta média; rodar 4 variantes; anotar tempo e tokens; classificar qualidade subjetiva; escrever a regra pessoal.

Uma skill combina descrição (trigger), instruções e (opcional) tools próprias. É a menor unidade que o agente reconhece como "capacidade plugável".

Quase tudo que você vai estender no DeerFlow tem formato de skill. Entender o contrato é obrigatório.

Descrição clara = trigger accuracy; escopo limitado; composição com outras skills; versionamento.

Famílias de skills prontas: deep-research, github-deep-research, systematic-literature-review, data-analysis, chart-visualization, academic-paper-review.

Muita demanda de "pesquisa" tem skill específica. Usar a skill certa muda qualidade drasticamente.

deep-research ≠ SLR; análise de dados aciona visualização automaticamente; revisão acadêmica tem formato próprio de saída.

ppt-generation, podcast-generation, newsletter-generation, video-generation, image-generation. Skills que entregam artefato final, não só texto.

Quase tudo que vira slide, áudio ou vídeo no fluxo de trabalho corporativo tem skill cobrindo. Economiza muita fricção.

Saídas são arquivos reais; formatos configuráveis; qualidade depende do modelo escolhido; bom complemento de research.

frontend-design, vercel-deploy-claimable, code-documentation, consulting-analysis, surprise-me. Skills de engenharia e apoio ao negócio.

São as que mostram o DeerFlow saindo do script "só research" e cobrindo fluxos reais de entrega.

vercel-deploy-claimable entrega URL; consulting-analysis tem formato específico de relatório; surprise-me é meta (escolhe por você).

O lead_agent lê a descrição de cada skill e decide qual (ou nenhuma) se aplica ao prompt atual. A qualidade da escolha depende da descrição.

Explica por que skill quase certa não é acionada — descrição pouco específica. Também por que forçar à mão às vezes compensa.

Descrição é o contrato; ambiguidade derruba accuracy; forçar invocação é válido; combinação de skills é natural.

Sintaxe de invocação explícita que diz ao lead_agent: "use skill X neste prompt", ignorando a heurística automática.

Útil para testes, comparativos e quando você sabe exatamente o que quer. Também derruba frustração com auto-seleção.

Invocação explícita não bloqueia composição; agente ainda pode chamar outras skills; o resultado fica no mesmo trace.

Rodar o mesmo tema em deep-research e em systematic-literature-review e comparar as saídas.

As duas skills parecem iguais de fora. Só comparando dá para entender onde uma é melhor que a outra — e quando nenhuma serve.

Escolher tema com literatura publicada; rodar as duas; comparar estrutura da saída, citações, profundidade; escrever a heurística de escolha.

Providers que alimentam as skills de pesquisa com resultados estruturados da web. Tavily e InfoQuest são os suportados por padrão.

Provider errado = resultados ruins mesmo com skill certa. E cada um tem trade-offs de custo, qualidade e freshness.

Tavily = rápido e barato; InfoQuest = curadoria; troca via config; quota importa em uso pesado.

Mecanismo para colocar arquivos no sandbox para que skills os leiam. Suporta texto, binário, planilhas, PDFs.

É o atalho para análise de dados sem configuração de ingestão. Entender o ciclo de vida do arquivo evita vazamento entre sessões.

Arquivo vive no sandbox; é limpo entre sessões; tamanho limitado; pode ser referenciado por nome no prompt.

O sandbox roda direto no host, sem isolamento. Zero overhead, zero proteção. Útil só em máquina de desenvolvimento dedicada.

É o modo mais comum para "quero testar rápido" — e o que mais gera acidentes. Saber quando não usar é metade do aprendizado.

Sem isolamento; rápido; compartilha home do usuário; jamais use em produção.

Cada execução em um container isolado com imagem controlada. Resolve 90% dos problemas de Local sem complexidade operacional.

É o default recomendado para uso pessoal e equipes pequenas. Entender a imagem base e os volumes economiza horas.

Container por execução; imagem customizável; volumes para persistir; supera Local em quase tudo.

Cada sessão vira um Pod com quotas de CPU/RAM/tempo, isolamento de rede e limpeza automática. Nível empresa.

Quando você hospeda o DeerFlow para um time, Docker não escala. K8s é o único caminho sensato para multi-tenant.

Provisioner customizável; network policies; image pull secrets; integra com observability do cluster.

Subir um CSV real e pedir análise com geração de gráficos — combinando data-analysis e chart-visualization.

Mostra upload, sandbox e composição automática de skills em uma só tarefa. É o exemplo mais honesto do que o DeerFlow faz bem.

CSV de amostra; prompt de análise; inspecionar artefatos gerados; conferir que gráficos foram salvos no sandbox; baixar resultado.

Fatos sobre você, o projeto, preferências e referências externas. O histórico da conversa não é memória — é contexto temporário.

A distinção entre memória e histórico é a mais importante e a menos ensinada. Confundir as duas gera expectativas erradas.

Memória sobrevive a sessões; histórico vive só na conversa; critério de salvamento é explícito; você pode forçar.

Quatro categorias: perfil do usuário, feedback de como trabalhar, fatos do projeto, e ponteiros para sistemas externos.

Sem categoria, tudo vira "fato" e a memória polui rápido. As categorias dão controle para revisar e limpar.

Cada tipo tem critério próprio; revisão por categoria; decaimento diferente para cada.

A UI expõe a memória como itens editáveis. Você lê, corrige, remove ou arquiva. É um diário, não uma caixa-preta.

Revisar regularmente é a diferença entre memória útil e memória envenenada.

Edição inline; delete com confirmação; export para backup; merge quando há duplicata.

Nem toda tarefa ganha com memória. Pesquisas continuadas ganham; exploração aberta perde; tarefa crítica exige memória limpa.

Saber quando desligar a memória evita que fatos velhos contaminem decisões novas.

On/off por sessão; memória por projeto; poisoning é real; viés de confirmação via memória antiga.

Criar um projeto de pesquisa contínua em três sessões separadas, verificando o que é carregado automaticamente em cada retorno.

Só a continuidade revela o que a memória faz bem e o que ela esquece ou inventa.

Sessão 1: contexto inicial; sessão 2: retomar e validar; sessão 3: contradição intencional e conferir o que foi sobrescrito.

Canal de entrada oficial que liga um bot do Telegram ao lead_agent, preservando sessão e memória por usuário.

É a integração mais rápida para "usar o DeerFlow no celular" sem subir frontend. Bom para demo e uso pessoal.

BotFather para criar; token em .env; sessão por chat; arquivos suportados nativamente.

App do Slack que roteia mensagens de canais ou DMs para o DeerFlow e responde com threads e artefatos anexados.

É onde a maioria dos times corporativos já trabalha. Plugar bem é a diferença entre "interessante" e "adotado".

Slack App com scopes; socket mode ou HTTP; sessão por thread; custom agents por canal.

Canais IM adicionais suportados nativamente. Essenciais se você trabalha em um time com presença na China ou no ecossistema ByteDance.

Mesmo fora dessas empresas, ler como o DeerFlow suporta esses canais é um ótimo estudo de caso de plugabilidade.

Abstração comum de canal IM; mesma API interna; webhook + callback; custom agents também se aplicam.

Integração nativa que envia cada execução como trace hierárquico para o LangSmith, incluindo tool calls e tokens.

Sem tracing, debug vira adivinhação. LangSmith é o caminho mais rápido para visualizar o que o agente está fazendo.

Traces com árvore de chamadas; custo por execução; filtros por skill; datasets para avaliação.

Alternativa open-source e self-hosted ao LangSmith, com o mesmo conceito de trace hierárquico e o mesmo ponto de integração.

Se você não pode mandar dados para um SaaS, Langfuse é o caminho. E o DeerFlow trata os dois como intercambiáveis.

Self-host em minutos; API compatível; dashboards customizáveis; ótimo para compliance.

Plugar um bot do Telegram ao DeerFlow, ativar LangSmith e conversar pelo celular enquanto observa traces no laptop.

Une duas peças que parecem separadas — IM e observabilidade — e mostra que a mesma execução é auditável em qualquer canal.

BotFather + token; habilitar Telegram no config; ativar LangSmith; enviar 3 prompts; conferir traces em tempo real.