💡 Como ler este módulo
A escolha de sandbox é uma decisão de risco, não de performance. Os tópicos 3-5 são curtos de propósito — o objetivo é você entender quando não usar cada um. Depois o lab costura web search + upload + sandbox numa tarefa real.
🌐 Providers de web search
Skills de pesquisa (deep-research, SLR, github-deep-research) não falam direto com Google ou Bing — passam por um provider de search que devolve resultados estruturados, já rankeados e prontos para consumo por LLM. O DeerFlow suporta Tavily e InfoQuest de fábrica, e a escolha não é neutra: provider errado derruba a qualidade mesmo com a skill certa.
🎯 Os dois suportados
- Tavily— API pensada para LLM, rápido, custo por query baixo, bom para queries curtas. Plano free decente para começar.
- InfoQuest— foco em curadoria e fontes confiáveis, custa mais, devolve resultados mais densos. Bom para research onde qualidade > quantidade.
📊 Comparativo
- Custo por query — Tavily ~5-10× mais barato que InfoQuest
- Latência — Tavily: ~1-2s, InfoQuest: ~3-5s
- Qualidade em nicho — InfoQuest vence, principalmente em fontes acadêmicas/regulatórias
- Freshness — Tavily atualiza mais rápido; InfoQuest tem indexação mais curada
- Cota — ambos têm limite, configure
max_queries_per_turnno YAML
💡 Dica prática
Comece com Tavily + free tier. Só migre para InfoQuest quando você notar que deep-research está citando blogs de qualidade duvidosa em um tema que deveria ter fontes acadêmicas. A migração é trocar duas linhas no config.yaml.
📁 Upload de arquivos
Upload no DeerFlow não é "enviar um PDF para o contexto do modelo". É colocar o arquivo no sandbox — o mesmo sistema de arquivos onde as skills executam código. Isso muda tudo: data-analysis pode abrir o CSV com pandas, code-documentation pode listar o diretório, chart-visualization pode salvar PNG no mesmo lugar. O modelo nunca vê o arquivo inteiro; vê o código que o manipula e o resultado do código.
🎯 Ciclo de vida do arquivo
- •Upload via UI → arquivo vai para o diretório de trabalho do sandbox daquela sessão
- •Referência por nome — skills acessam pelo nome do arquivo diretamente no prompt
- •Vida útil — enquanto a sessão existir, o arquivo persiste. Sessão encerrada = sandbox limpo
- •Artefatos gerados — gráficos, PPTs, relatórios criados pelas skills também viram download na UI
- •Limite — tamanho de upload configurável, default conservador (~50MB por arquivo)
🚨 Alerta: vazamento entre sessões
No sandbox Local, o diretório de trabalho pode ser compartilhado entre sessões se você não configurar isolamento. Isso significa que um arquivo que você subiu numa sessão "pesquisa A" pode ficar visível numa sessão "pesquisa B" — e pior, pode ser lido acidentalmente por uma skill.
Fix: use Docker ou K8s (já isolam por sessão), ou configure sandbox.workdir_per_session: true se precisar ficar no Local.
💻 Sandbox Local
O modo mais simples e mais perigoso. Sandbox Local roda o código gerado no próprio host, sob o usuário que iniciou o DeerFlow, sem nenhuma camada de isolamento. Zero overhead. Zero proteção. É útil em uma situação: máquina de desenvolvimento dedicada, sem credenciais importantes, sem rede crítica.
🚨 Alerta vermelho
Rodar Local na sua máquina de trabalho significa que qualquer código gerado pelo LLM tem acesso ao seu home directory, às suas SSH keys, aos seus tokens de cloud, ao seu banco do navegador. Não importa quão benigno seja o prompt — prompt injection é real, alucinação é real, erro do modelo é real.
Casos aceitáveis de Local: máquina descartável de dev, CI sem secrets, laptop usado apenas para demos.
🎯 O que Local oferece em troca
- •Latência zero — sem container, sem Pod, sem rede entre processos
- •Acesso ao ambiente — bibliotecas que você já instalou localmente, GPUs locais
- •Debug direto — stack trace roda no mesmo Python que você monitora
- •Zero setup — funciona sem Docker daemon, sem kubeconfig
🐳 Sandbox Docker
O default recomendado para uso pessoal e equipes pequenas. Cada execução de código vive num container descartável baseado na imagem oficial do DeerFlow sandbox, com filesystem isolado, rede controlada e tempo de vida definido. Resolve 90% dos problemas de Local sem complexidade operacional.
🎯 Por que Docker é o default
Porque é o menor overhead aceitável para rodar código de terceiros — e o código gerado por LLM é, em todo sentido prático, código de terceiros. O container pode ser reciclado a cada sessão, os mounts são explícitos, a rede pode ser restrita, e nada disso exige kubernetes.
- •Imagem base — python + uv + bibliotecas comuns, mantida pelo DeerFlow
- •Mounts explícitos — só o workdir da sessão, nada do host além disso
- •Tempo de vida — container dura enquanto a sessão existe, é reciclado no reset
- •Rede — configurável. Por default permite saída para APIs; pode ser restringida.
💡 Imagem custom
Se seu fluxo precisa de uma biblioteca específica toda hora (exemplo: polars, scikit-learn completo, uma lib interna), é mais rápido estender a imagem base do que mandar o agente instalar dinamicamente a cada execução. Um Dockerfile de 5 linhas + sandbox.image: myorg/deerflow-sandbox:custom no YAML.
☸️ Sandbox Kubernetes
Para multi-tenant em produção, Docker não escala. Você precisa de quotas por sessão, isolamento de rede real, limpeza garantida, observabilidade integrada. Kubernetes vira a única resposta sensata. Cada sessão do DeerFlow instancia um Pod com ServiceAccount próprio, NetworkPolicy, limites de CPU/RAM/tempo e teardown automático.
Configurar provisioner
No config.yaml, apontar para o cluster (kubeconfig ou in-cluster), definir namespace dedicado, imagem base e imagePullSecrets se for registry privado.
Definir quotas padrão
CPU request/limit, memória, ephemeral-storage, tempo máximo de vida. Valores sensatos: 500m-2 CPU, 1-4 GiB RAM, 30min de timeout. Ajuste pelo seu workload.
NetworkPolicy
Restringir saída do Pod apenas para os endpoints necessários (providers de LLM, providers de search, APIs internas permitidas). Nega tudo o mais. É a camada mais importante.
Observabilidade
Integrar com o stack do cluster — Prometheus, Loki, Grafana. O DeerFlow exporta métricas por Pod (tokens consumidos, tempo por skill, falhas). Dashboard pronto em minutos.
🧪 Lab: CSV → análise + gráficos
O exemplo mais honesto do que o DeerFlow faz bem: você sobe um CSV, pede análise, recebe resumo textual e gráficos salvos como artefatos. Tudo em um único turno. É data-analysis + chart-visualization compostos automaticamente.
🎯 O que você vai fazer
Subir um CSV real de tamanho moderado, pedir análise exploratória com visualizações, baixar os artefatos gerados e conferir no trace que a composição de skills aconteceu.
📊 Por que esse lab
Ele toca três coisas em uma tarefa: upload (fluxo de arquivo), sandbox (execução de pandas/matplotlib real), e composição automática (data-analysis chama chart-visualization sem você pedir). Você vê que o harness faz mais do que rotear prompt.
Arranjar o CSV
Algo com 1k-50k linhas, pelo menos 5 colunas, misture numérico e categórico. Um dataset público de Kaggle serve. Evite dados pessoais reais.
Upload + prompt
Suba pelo botão de upload da UI. Prompt sugerido: "Faça uma análise exploratória deste CSV, destaque 3 padrões interessantes e gere visualizações correspondentes." Deixe a auto-seleção de skill rodar.
Observar o trace
Confirme: data-analysis acionada → código pandas executado no sandbox → chart-visualization acionada com referência aos dados → PNGs salvos. Anote quantos turnos internos aconteceram.
Baixar os artefatos
A UI lista os arquivos gerados no sandbox. Baixe os PNGs, confira que são gráficos de verdade (não descrições textuais), compare com o texto da análise. Se não bate, o prompt precisa ser mais específico.
Variação: forçar o sandbox
Se você estiver em Local, troque para Docker temporariamente e refaça. Sinta na pele o que muda (latência, isolamento, onde o PNG mora). O trade-off fica concreto.
📝 Resumo do Módulo
Próximo Módulo:
1.6 — 🧠 Memória de longo prazo
O que o DeerFlow lembra entre sessões, como revisar, e quando a memória ajuda ou atrapalha.