💡 Como ler este módulo
Este é o único módulo do curso sem lab. O objetivo é instalar vocabulário na sua cabeça para que o resto faça sentido. Leia inteiro antes de passar para o 1.2 — o tempo investido aqui é pago 10x nos próximos módulos.
🏛️ O que é um super agent harness
A palavra "agent" virou elástica. Virou sinônimo de qualquer coisa que chama LLM em loop. Um super agent harness é uma categoria específica: é a camada que fica entre o modelo e tudo que ele precisa fazer no mundo — skills, sub-agents, memória, sandbox, canais de comunicação. Não é um chatbot com tools. Não é um framework de agente. É um hospedeiro completo para trabalhos não-triviais.
🎯 Conceito Central
Um harness é um orquestrador persistente. Ele recebe um pedido, planeja, aciona skills, roda código em sandbox, consulta memória, coordena sub-agents e devolve o resultado. Tudo sem que o modelo precise entender como cada peça funciona.
- •Orquestra — decide o quê fazer e em que ordem
- •Isola — cada passo roda onde deve, com contexto certo
- •Persiste — memória e traces sobrevivem à sessão
- •Estende — skills, tools, providers, canais IM são plugáveis
✓ O que harness É
- ✓Plataforma de hospedagem de agentes
- ✓Extensível por skills e providers
- ✓Multi-canal (web, IM, API)
- ✓Observável de ponta a ponta
✗ O que harness NÃO é
- ✗Um chatbot (chatbot não planeja e não executa código)
- ✗Um framework (framework é biblioteca, não produto rodando)
- ✗Um IDE-agent (IDE vive dentro do editor de código)
- ✗Um pipeline fixo (pipeline não decide o próximo passo)
🔄 A virada da v1 para a v2
O DeerFlow v1 era "Deep Research" — um produto focado, com pipeline relativamente fixo para pesquisar tema → gerar relatório. A v2 é uma reescrita completa. Não compartilha código com a v1. Não é upgrade. O escopo mudou: de produto de research para harness de propósito geral. Entender isso evita procurar documentação no lugar errado.
DeerFlow v1 — Deep Research
Produto focado, fluxo quase linear
Um único caso de uso tratado muito bem: pesquisa profunda com citação de fontes. A arquitetura refletia esse foco — pipeline, não grafo. Pouco espaço para extensão de terceiros.
A reescrita
Decisão de zerar e reconstruir
Quando a ByteDance quis que o DeerFlow cobrisse podcast, PPT, código, análise, decidiu que forçar essas capacidades sobre o pipeline da v1 era um erro. A v2 começou do zero com LangGraph como substrato.
DeerFlow v2 — Harness genérico
Plataforma multi-uso, extensível
Lead agent sobre um grafo LangGraph, catálogo de skills plugáveis, memória de primeira classe, sandbox configurável e múltiplos canais de entrada. Deep Research agora é só uma skill entre muitas.
⚠️ Atenção: não há migração automática
Se você tem conteúdo, configs ou hacks feitos para a v1, não dá para importar. As arquiteturas são incompatíveis. Muita documentação antiga na internet ainda se refere a v1 sem deixar isso claro — desconfie de qualquer guia que não mencione LangGraph, skills ou lead_agent.
🧩 Pilar 1: Skills
A skill é a unidade de capacidade do DeerFlow. É um pacote com três coisas: uma descrição (para o agente saber quando acionar), um conjunto de instruções (para saber como executar) e, opcionalmente, tools próprias. É isto e nada mais.
🎯 Por que skill é o pilar mais importante
Porque é o principal ponto de extensão. Sub-agents, sandbox e memória são infraestrutura — você usa, mas raramente precisa reescrever. Skills, você escreve. A maior parte do que diferencia um DeerFlow genérico de um DeerFlow "feito para a sua empresa" está no catálogo de skills que você adicionou.
- •Descrição é contrato — erre a descrição e a skill nunca é acionada
- •Escopo limitado — uma skill para uma coisa, composição faz o resto
- •Versionável — skills são arquivos de texto, entram no git
💡 Dica prática
Antes de criar uma skill, procure no catálogo público. Tem mais skill pronta do que você imagina — deep-research, data-analysis, ppt-generation, podcast-generation, code-documentation, consulting-analysis. Ver a lista completa evita reinventar.
👥 Pilar 2: Sub-agents
Um sub-agent é um agente filho que o lead_agent invoca para fazer um pedaço da tarefa com contexto isolado, e que retorna apenas o resultado útil. Na prática: "vai ler esses 50 artigos e me devolve só as 3 conclusões que importam". O lead_agent não precisa carregar os 50 artigos inteiros na sua janela.
🎯 Para que servem
Sub-agents resolvem o problema de poluição de contexto. Sem eles, qualquer pesquisa longa enche a janela do agente principal com lixo intermediário — trechos de artigos, outputs de comandos, resultados parciais. Com eles, o agente principal mantém só o essencial.
📊 Dados práticos
- 5-10× — redução típica de tokens consumidos pelo agente principal em pesquisas longas
- Contexto isolado — sub-agent começa do zero, não vê o histórico do pai
- Retorno resumido — só o que você pedir explicitamente volta para o pai
- Paralelizável — múltiplos sub-agents podem rodar ao mesmo tempo
📦 Pilar 3: Sandbox
Sandbox é onde código gerado pelo agente roda. O DeerFlow oferece três modos — Local, Docker, Kubernetes — com trade-offs entre conveniência e segurança. A decisão entre eles não é de performance; é de risco.
🎯 Os três modos em uma frase
- Local— rápido, sem isolamento, só em máquina dedicada de dev.
- Docker— um container por execução, default recomendado para uso pessoal e equipes pequenas.
- K8s— um Pod com quotas e isolamento de rede, único viável para multi-tenant em produção.
🚨 Alerta de segurança
Rodar código gerado por LLM no host sem sandbox é equivalente a executar um anexo de email de remetente desconhecido. Não importa quão bem-intencionado esteja o prompt — o modelo pode alucinar, ser induzido via prompt injection, ou simplesmente errar.
Regra prática: use Local apenas em máquina sem credenciais importantes. Para tudo o mais, Docker.
📐 Pilar 4: Context Engineering
Context engineering é o conjunto de técnicas que decidem o que entra e o que sai da janela de contexto em cada turno do agente. Parece assunto interno — não é. É o motivo principal pelo qual um mesmo modelo parece "brilhante" num harness e "burro" em outro.
🎯 O que entra na janela
Em cada turno, o DeerFlow decide o que colocar no contexto do modelo: o prompt do usuário, o histórico relevante (não todo), memórias aplicáveis, instruções de skills ativas, resultados de tools recentes. O que fica de fora é tão importante quanto o que entra.
- •Compactação — histórico antigo é resumido automaticamente
- •Seleção — só memórias relevantes para o turno entram
- •Prioridade — instrução atual vence histórico antigo
- •Guardrails — instruções de segurança não podem ser sobrescritas
✓ O que ajuda o contexto
- ✓Dividir tarefas grandes via sub-agents
- ✓Limpar memórias obsoletas regularmente
- ✓Usar plan mode para tarefas longas
- ✓Começar sessão nova quando o tema muda
✗ O que envenena o contexto
- ✗Colar blocos gigantes de texto no prompt
- ✗Acumular memória sem revisar
- ✗Conversar sobre 5 tópicos não-relacionados
- ✗Ignorar a compactação automática
💾 Pilar 5: Memory
Memória é o armazenamento de longo prazo que sobrevive à conversa. Guarda perfil do usuário, preferências de trabalho, fatos do projeto e referências a sistemas externos. É diferente de histórico de sessão: histórico morre quando a conversa fecha; memória não.
🎯 As quatro categorias
- User— quem é você, o que faz, como prefere trabalhar
- Feedback— correções e aprovações explícitas que o agente deve respeitar
- Project— fatos do projeto atual que não moram no código
- Reference— ponteiros para sistemas externos (dashboards, issue trackers, docs)
💡 Memória é um diário, não uma caixa-preta
No DeerFlow v2, você vê cada item de memória. Pode editar. Pode remover. Pode exportar para backup. Isso é deliberado — memória opaca é o caminho mais rápido para memory poisoning. Revise semanalmente e a memória vira um ativo; ignore e vira passivo.
🎬 Casos de uso reais
Para fechar o big picture, o que o DeerFlow realmente faz bem hoje. Os casos abaixo não são publicidade — são os domínios em que o catálogo de skills públicas já resolve 80% do problema sem customização.
Deep research e revisão de literatura
Skills: deep-research, systematic-literature-review, academic-paper-review
Pesquisas estruturadas com citação de fontes, comparativo de papers, levantamento bibliográfico sistemático. É a cara da v1, mas agora como uma capacidade entre outras.
Análise de dados com gráficos
Skills: data-analysis, chart-visualization
Sobe um CSV, pede análise e recebe de volta resumo textual + gráficos em arquivos reais. O diferencial é a composição automática: data-analysis aciona chart-visualization sem precisar pedir.
Mídia: PPT, podcast, vídeo, newsletter
Skills: ppt-generation, podcast-generation, video-generation, newsletter-generation
Geração de artefatos de comunicação. A qualidade depende do modelo e da descrição, mas o formato final (arquivo .pptx, .mp3, .mp4, .md) sai pronto.
Engenharia de software
Skills: frontend-design, code-documentation, vercel-deploy-claimable
Não é o caso de uso mais forte do DeerFlow (Claude Code e IDE-agents são mais fortes aqui), mas funciona bem para geração de UI, documentação de código e deploys pontuais.
Consultoria e análise de negócio
Skills: consulting-analysis
Relatórios em formato específico (executive summary, SWOT, recomendações). Útil para quem quer resposta com estrutura fixa, não texto corrido.
📝 Resumo do Módulo
Próximo Módulo:
1.2 — 🚀 Instalação e primeiro "olá mundo"
Do clone ao primeiro prompt rodando via Docker. Inclui lab hands-on.