MÓDULO 1.2

🚀 Instalação e primeiro "olá mundo"

Do clone ao primeiro prompt rodando no navegador. Você vai aprender onde cada arquivo mora, como escolher um provider de LLM sem se enforcar em custo, e terminar o módulo com uma pergunta real respondida pelo DeerFlow.

6
Tópicos
40
Minutos
Básico
Nível
Prático
Tipo

💡 Como ler este módulo

Leia os cinco primeiros tópicos antes de começar o lab. Instalar sem entender onde cada coisa mora é o atalho mais rápido para travar na primeira hora. Reserve 40 minutos inteiros — a última seção é hands-on e paga todo o resto.

1

🧙 make setup vs. make config

O DeerFlow oferece dois caminhos para sair do zero: make setup é um wizard interativo no terminal que pergunta provider, chave, sandbox preferido e gera os arquivos por você. make config assume que você quer editar na mão e só copia os templates de config.example.yaml e .env.example para os lugares certos. Os dois chegam no mesmo lugar — só o conforto inicial muda.

🎯 Quando escolher cada um

  • setup— primeira instalação, alguém novo no time, workshop, demonstração. Você responde 4–6 perguntas e sai com algo funcional.
  • config— segunda máquina, re-deploy, CI/CD, migração de ambiente. Você abre os arquivos, altera três linhas, roda o doctor.

💡 Dica prática

Use make setup na sua máquina de dev hoje, depois abra config.yaml e .env e leia. Você vai reconhecer o que o wizard fez e nunca mais vai precisar dele. É o melhor tour guiado do repositório.

2

📄 config.yaml e .env — o que mora onde

A separação é deliberada e segue o princípio de 12-factor: config.yaml contém decisões estruturais (que providers estão ativos, qual sandbox, quais skills carregar, limites de tokens), .env contém apenas segredos (API keys, tokens, URLs com credencial embutida). O YAML entra no git; o .env nunca.

🎯 A regra mental

Se o valor muda entre ambientes (dev, staging, prod) e é público, vai no YAML. Se muda entre ambientes e é secreto, vai no .env. Se é o mesmo em todo lugar, vai no YAML hardcoded. Substituição com ${VAR} no YAML puxa do .env em tempo de leitura.

  • •config.yaml — providers, skills ativas, sandbox mode, memory paths, limites
  • •.env — OPENAI_API_KEY, ANTHROPIC_API_KEY, TAVILY_API_KEY, TELEGRAM_BOT_TOKEN
  • •.gitignore — o .env já está listado no template. Confira antes do primeiro commit.

🚨 Alerta: chave vazada em git

Se você commitar uma API key por engano, rotacione imediatamente. Não adianta fazer git rm; a chave fica no histórico e scanners automáticos acham em minutos. GitHub, GitLab e providers de LLM têm programas de detecção que avisam — e alguns revogam a chave sozinhos.

Profilaxia: instale gitleaks ou pre-commit no repo. Custa 2 minutos e evita o desastre.

✓ Fazer

  • ✓Manter .env fora do git, sempre
  • ✓Versionar config.example.yaml e .env.example
  • ✓Usar ${VAR} no YAML para puxar segredos
  • ✓Rodar make doctor após editar qualquer um

✗ Evitar

  • ✗Colar chave direto no config.yaml
  • ✗Compartilhar .env por Slack/WhatsApp
  • ✗Editar YAML com aspas trocadas (quebra parsing)
  • ✗Ignorar warnings do doctor "por enquanto"
3

🔌 Escolher um provider

O DeerFlow trata multi-provider como cidadão de primeira classe. Não há um "provider default" — você escolhe conscientemente. Cada skill pode inclusive fixar um modelo preferido, o que permite usar Claude Sonnet para deep-research e GPT-4o-mini para classificação barata, no mesmo fluxo. A decisão não é religiosa; é de custo, latência, qualidade e privacidade.

1

OpenAI direto

gpt-4o, gpt-4o-mini, o1

Baseline estável, documentação grande, latência boa. Bom default se você já tem conta. Caro para uso pesado.

2

OpenRouter

Proxy para 100+ modelos

Uma chave, muitos modelos, incluindo Claude, Gemini, Llama hosted. Ótimo para experimentar. Cobra spread pequeno sobre o preço original.

3

Claude Code OAuth

Reaproveita assinatura Claude Max

Se você já paga Claude Max, o DeerFlow fala com Claude via OAuth local sem consumir crédito de API separado. Limite diário aplica.

4

Codex CLI

CLI-backed para assinantes

Mesmo padrão do Claude OAuth, mas via Codex. Útil para quem tem ChatGPT Pro e quer usar o Codex sem pagar API à parte.

5

vLLM local

Modelos open-weights em GPU própria

Llama, Qwen, Mistral rodando em GPU local via vLLM. Latência depende do hardware; privacidade total. Bom para dados sensíveis.

6

Doubao, DeepSeek, Kimi

Providers asiáticos suportados de fábrica

Preço agressivo, qualidade competitiva em chinês e razoável em inglês. DeepSeek-V3 é destaque em custo-benefício. Doubao vem da ByteDance (mesma casa do DeerFlow).

📊 Comparativo rápido

  • Menor custo por token — DeepSeek, Kimi, Llama local (amortizado)
  • Menor latência hosted — Groq, gpt-4o-mini, Gemini Flash
  • Melhor raciocínio — o1, Claude Sonnet (thinking), Gemini 2.5 Pro
  • Melhor privacidade — vLLM local (dados nunca saem)
  • Mais fácil de começar — OpenRouter com uma única chave
4

🩺 make doctor — o amigo que ninguém usa

make doctor é o comando de diagnóstico do DeerFlow. Ele valida o YAML, pinga cada provider com uma requisição mínima, confere que o sandbox escolhido está disponível (Docker daemon rodando, kubeconfig lendo cluster, etc.), checa versões de dependências e reporta cada problema com uma sugestão de fix acionável. É o comando mais subutilizado do repositório.

🎯 O que o doctor testa

  • •Parsing do YAML — indentação errada, aspas quebradas, chaves duplicadas
  • •Substituição de variáveis — ${FOO} referenciado no YAML e ausente no .env
  • •Ping de providers — cada chave responde a uma requisição de teste
  • •Sandbox availability — Docker rodando, K8s acessível, Local com permissões
  • •Versões — Python, Node, npm, docker, kubectl dentro do esperado
  • •Skills carregáveis — descrições presentes, dependências instaladas

💡 Regra de ouro

Rode o doctor após qualquer mudança de config. Não depois de notar que "algo está estranho" — imediatamente depois de salvar. Também é seu primeiro comando ao pedir ajuda: 90% dos tickets que chegam nos canais do DeerFlow já têm resposta pronta na saída do doctor. Leia antes de perguntar.

5

🐳 Subir via Docker

O DeerFlow oferece dois alvos make para o caminho Docker: make docker-init baixa a imagem base, monta volumes de memória e skills e prepara o frontend; make docker-start sobe os serviços (backend + frontend + sandbox) e expõe a UI em http://localhost:3000. Tudo que você precisa fazer é abrir o navegador e conversar.

🎯 Por que Docker é o default

Equilibra conveniência e segurança. Nem tão cru quanto rodar no host (evita poluir seu Python, evita acidente do sandbox escrever onde não deve) nem tão complexo quanto K8s (não precisa de cluster, ingress, secrets manager).

  • •Imagem base estável — Python + Node + uv já preparados
  • •Volumes persistentes — memória e skills sobrevivem a restart
  • •Reset fácil — make docker-clean volta tudo ao zero em segundos
  • •Portas conhecidas — 3000 (UI), 8000 (API), 8001 (sandbox bridge)

💡 Quando o reset é a resposta

Se algo parou de funcionar depois que você mexeu em várias configs, não tente debugar cada camada. Rode make docker-clean && make docker-init && make docker-start. Leva 2 minutos e elimina 70% dos estados ruins. Debug vale a pena quando você sabe o que mudou — não quando está procurando o que quebrou.

6

🧪 Lab: primeira pergunta real

Chegou a hora. Em vez de "diga oi", você vai rodar uma pergunta que exercita uma skill de verdade e observar o loop plan → execute → resultado ao vivo no frontend. O objetivo não é a resposta bonita; é entender a mecânica.

🎯 O que você vai fazer

Subir o DeerFlow via Docker, abrir o frontend, pedir uma pesquisa curta (não um fato) e inspecionar o trace da execução. Depois rodar a mesma pergunta forçando a skill deep-research e comparar.

📊 Por que esse lab

Sair do "hello world" já na primeira execução quebra a tentação de achar que o agente é mágica. Você vê a divisão planejamento → execução → resposta, vê o custo em tokens, vê qual skill foi acionada (ou não). A partir daqui o resto do curso faz sentido.

1

Preparar

git clone do repo, rodar make setup, escolher um provider (OpenRouter é o mais fácil para começar), colar a chave, finalizar o wizard. Rodar make doctor e confirmar que está tudo verde antes de seguir.

2

Subir

Rodar make docker-init (a primeira vez demora alguns minutos — é download de imagem). Depois make docker-start. Abrir http://localhost:3000 no navegador e confirmar que a UI carrega.

3

Primeira pergunta

Peça algo do tipo "quais são as três maiores diferenças entre LangGraph e AutoGen em 2026, com fontes". Não é um fato direto — força o agente a planejar. Observe o painel de traces abrindo a sequência de passos.

4

Inspecionar o trace

Veja qual skill foi acionada, quantas chamadas a providers de search aconteceram, quantos tokens foram consumidos. Anote o tempo total e o custo estimado.

5

Forçar a skill

Repita a mesma pergunta agora pedindo explicitamente deep-research. Compare: mudou a estrutura da saída? mudou o custo? A comparação treina sua intuição para o próximo módulo.

📝 Resumo do Módulo

✓
setup vs. config são o mesmo destino — wizard para começar, edição manual para reproduzir. Use setup uma vez, leia os arquivos, migre para config.
✓
config.yaml é estrutura, .env é segredo — nunca misture. .env fora do git, sempre. Use ${VAR} para puxar segredos no YAML.
✓
Multi-provider é cidadão de primeira classe — OpenAI, OpenRouter, Claude OAuth, Codex CLI, vLLM, DeepSeek, Kimi, Doubao. A escolha é de custo, latência, qualidade e privacidade.
✓
make doctor é obrigatório — rode após qualquer mudança. 90% dos problemas já têm detecção pronta.
✓
Docker é o default razoável — equilibra conveniência e segurança. docker-clean resolve a maioria dos estados ruins.
✓
Primeira pergunta real revela o loop — planejamento, execução, trace, custo. A partir daqui não é mais mágica.

Próximo Módulo:

1.3 — 🖥️ A interface e o loop básico

Tour pelo frontend Next.js, anatomia de uma conversa e os modos plan/thinking que mais mudam o resultado.

← Módulo Anterior Voltar para Trilha Próximo Módulo →