DeerFlow 2.0: como usar o superagente open source da ByteDance

O DeerFlow 2.0 é um framework aberto da ByteDance para executar agentes de IA em tarefas longas: pesquisas que exigem muitas etapas, programação, produção de arquivos, uso de navegador, divisão de trabalho entre subagentes e continuidade por memória. Em vez de ser um chatbot isolado, ele funciona como um harness: uma camada que combina modelos, ferramentas, sandboxes, skills, persistência e canais de mensagem em um ambiente operacional.

O projeto entrou na sua segunda geração em 2026 com uma reescrita completa, sem compartilhar código com a linha 1.x. A mudança é relevante porque o foco não é somente “deep research”: DeerFlow 2.0 organiza também automação de tarefas, desenvolvimento assistido, workflows com subagentes, recuperação de conhecimento e execução com arquivos. Este guia explica o que ele faz, como instalar de forma segura e quais escolhas precisam ser feitas antes de colocá-lo em uma rede ou conectá-lo a credenciais.

O que é o DeerFlow 2.0

DeerFlow significa Deep Exploration and Efficient Research Flow. A definição curta do próprio projeto é “super agent harness”: um sistema que orquestra agentes, subagentes, memória, sandboxes, ferramentas e skills extensíveis. A função dele é permitir que uma tarefa atravesse vários passos sem que o usuário tenha de montar manualmente uma cadeia de prompts, arquivos e chamadas de ferramenta.

Na prática, o DeerFlow pode receber uma pergunta ampla, dividir a investigação em subproblemas, pesquisar fontes, registrar descobertas, criar artefatos em um sandbox, pedir revisão a outro agente e devolver arquivos ou uma resposta final. Ele também pode servir como base para tarefas de programação, análise de documentos, pesquisas recorrentes e operações em canais de mensagem — desde que o operador configure as permissões e os provedores com cuidado.

O projeto não é um modelo de IA. Ele precisa de pelo menos um modelo configurado para pensar e chamar ferramentas. Ele também não entrega automaticamente chaves de API, busca paga, capacidade de GPU ou segurança de produção. Essas partes são escolhas do operador.

O que mudou na versão 2

O DeerFlow 2.0 foi reescrito do zero. Quem usava a primeira versão para pesquisa profunda deve saber que o branch 1.x continua sendo o local do framework anterior; a linha principal passou para uma arquitetura mais ampla de agente persistente.

A ampliação aparece em recursos como memória de longo prazo, metas de sessão, arquivamento de conversas, projetos, tarefas agendadas, workbench de terminal, controle de navegador, skills exportáveis e subagentes. Em outras palavras, o projeto tenta cobrir o ciclo de vida de uma tarefa: receber contexto, planejar, agir, produzir arquivos, registrar resultados e retomar o trabalho posteriormente.

Principais recursos

• Subagentes: um agente principal pode delegar pesquisas, auditorias, escrita, código ou outras frentes independentes.
• Memória e contexto: o sistema oferece memória de longo prazo, objetivos de sessão, compactação de contexto e leitura de conversas referenciadas.
• Skills e ferramentas: capacidades podem ser adicionadas como skills, enquanto ferramentas dão acesso a busca, leitura de páginas, arquivos, terminal, navegador e integrações.
• Sandbox e sistema de arquivos: tarefas que exigem gerar arquivos ou executar código podem usar ambientes isolados, conforme a configuração escolhida.
• Browser agentic: o projeto inclui controle de navegador para fluxos que dependem de páginas e interfaces web.
• Projetos e documentos: há instruções por projeto, estante de documentos, arquivamento e lixeira para separar contextos de trabalho.
• Tarefas programadas: jobs recorrentes podem rodar para monitoramento, pesquisa ou fluxos operacionais.
• MCP e canais de mensagem: a plataforma pode atuar com integrações externas, incluindo servidor MCP e canais de IM, mas essa superfície exige controles de acesso rigorosos.
• Múltiplos provedores: a configuração aceita provedores compatíveis com OpenAI, Anthropic, DeepSeek, Gemini, OpenRouter, vLLM, Codex CLI, Claude Code OAuth e outros descritos no projeto.

Requisitos: não trate o DeerFlow como um app leve

O repositório declara Python 3.12 ou superior e Node.js 22 ou superior. Para o caminho de desenvolvimento local, a documentação também verifica pnpm, uv e nginx. Para Docker, o projeto pede Docker Engine ou Docker Desktop com Docker Compose v2.24 ou mais recente.

A própria documentação fornece uma referência de capacidade. Para avaliação local, o ponto de partida indicado é 4 vCPUs, 8 GB de RAM e 20 GB de SSD livre; a recomendação sobe para 8 vCPUs e 16 GB. Para desenvolvimento com Docker, o ponto inicial é 4 vCPUs, 8 GB de RAM e 25 GB de espaço livre. Para um servidor persistente com cargas multiagente, o projeto recomenda começar em 8 vCPUs, 16 GB de RAM e 40 GB de SSD, preferindo 16 vCPUs e 32 GB para cenários mais intensos.

Esses números cobrem o harness, não um LLM local. Se você também hospedar um modelo, banco vetorial ou serviços de browser remoto, dimensione cada componente separadamente. Uma máquina pequena pode até abrir a interface, mas isso não significa que suportará subagentes, sandboxes e múltiplas execuções com estabilidade.

Instalação: Docker é o caminho recomendado

O guia de instalação do próprio DeerFlow pede que um agente de código priorize Docker quando ele já está disponível. Isso reduz diferenças entre sistemas, evita instalar dependências de Python e front-end diretamente no host e torna o ambiente mais reproduzível.

1. Clone o repositório

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

Na análise do NoticIA, o checkout foi feito no commit 38e6be638bc79daa1a16ac314aa14d5460f88c6c, publicado em 1º de novembro de 2026. O repositório está em desenvolvimento ativo, então comandos, opções e exemplos podem mudar.

2. Rode o assistente de configuração

make setup

O wizard cria um config.yaml mínimo e registra valores de ambiente no .env. Ele orienta a escolha de provedor de LLM, busca web opcional e preferências de execução, como sandbox, acesso a Bash e ferramentas de escrita de arquivo. Não copie uma chave em prompts, em arquivos de skill ou no repositório Git. Guarde credenciais somente no mecanismo de configuração previsto para a implantação.

Se você quiser configurar manualmente, o projeto disponibiliza:

make config

Esse comando copia a referência de configuração, enquanto config.example.yaml documenta modelos, provedores, limites de subagentes, opções de sandbox e rotas de autenticação.

3. Prepare o ambiente Docker

make docker-init
make docker-start
make docker-logs

make docker-init baixa a imagem de sandbox necessária. make docker-start inicia os serviços de desenvolvimento e detecta o modo de sandbox definido no config.yaml. make docker-logs serve para acompanhar gateway, frontend e os erros de inicialização. O endereço padrão publicado pelo projeto é http://localhost:2026.

Para uma implantação de produção local, o fluxo documentado é:

make up
make down

O comando make up constrói as imagens e espera o endpoint de saúde do Gateway. O projeto alerta que um ambiente persistente precisa de banco configurado, preferencialmente SQLite para casos simples ou PostgreSQL para cenários mais robustos e distribuídos.

Alternativa: desenvolvimento local sem Docker

Se Docker não for uma opção, há um caminho local. Primeiro verifique se as ferramentas exigidas existem:

make check

Depois instale dependências do backend, frontend e hooks:

make install

Por fim, suba os serviços em modo de desenvolvimento:

make dev

Em Windows, a documentação recomenda Git Bash para esse fluxo. Ela não declara suporte aos scripts de serviço em cmd.exe ou PowerShell nativos, e também não garante WSL porque alguns scripts dependem de utilitários do Git for Windows.

O modo local é útil para desenvolver e depurar, mas Docker tende a ser mais previsível. Não misture os dois caminhos sem necessidade: escolha um, valide o config.yaml e mantenha os dados de runtime separados do código-fonte.

Como configurar modelos e provedores

O DeerFlow aceita modelos configurados em YAML e também oferece um fluxo administrativo em Settings → Models para adicionar modelos compatíveis com Chat Completions. Em configuração manual, uma entrada especifica nome interno, nome exibido, classe de provider, ID do modelo, chave e, se necessário, base_url.

models:
  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1

O exemplo é um formato de configuração, não uma recomendação de modelo. A escolha deve considerar capacidade de tool calling, visão, contexto, latência, preço, requisitos de reasoning e política de dados. Modelos configurados por YAML permanecem somente leitura na interface e têm precedência caso haja conflito de nome com entradas adicionadas pelo painel.

O projeto também documenta provedores por CLI. Para Codex, a configuração pode usar o provedor próprio que lê a autenticação de ~/.codex/auth.json. Para Claude Code, há suporte a OAuth e a caminhos de credenciais. Isso pode simplificar um ambiente já autenticado, mas não elimina a responsabilidade de controlar qual conta será usada e quais permissões ela possui.

Subagentes, sandboxes e browser: onde está o valor — e o risco

O DeerFlow se torna mais interessante quando uma tarefa é grande demais para uma única resposta. O agente principal pode quebrar a missão em pesquisa, verificação, código, síntese e revisão. O sandbox permite que uma execução crie ou modifique arquivos sem confundir o espaço de trabalho principal; o navegador expande a capacidade para sistemas que não têm API ou exigem inspeção visual.

Mas essas mesmas capacidades tornam o ambiente sensível. Um agente com navegador, shell, ferramentas de arquivo, MCP e uma entrada de chat externo tem uma superfície de ataque maior que um chatbot comum. A documentação do DeerFlow destaca que uma implantação inadequada pode introduzir riscos e que a administração do Gateway é equivalente à execução de código.

Na prática, siga quatro regras:

1. Não exponha a interface publicamente sem autenticação, HTTPS e política de rede.
2. Comece com permissões mínimas: ferramentas de escrita, Bash e aprovação automática devem ser ativadas apenas quando uma tarefa confiável realmente precisar delas.
3. Trate mensagens externas como conteúdo não confiável: um canal de Telegram, Slack ou outro IM pode carregar prompt injection e não deve ganhar privilégios por estar conectado.
4. Isole backends de busca e crawling: ferramentas que fazem fetch em nome do agente precisam bloquear redes privadas, loopback, metadata de cloud e destinos não verificáveis quando operadas como serviços delegados.

Skills, MCP, projetos e memória

Skills são pacotes de instruções e recursos para um tipo de trabalho: por exemplo, produzir relatório, revisar código, criar apresentação ou interagir com uma API. O DeerFlow permite estender o comportamento do lead agent e dos subagentes sem alterar diretamente os templates centrais. Esse desenho é útil para padronizar processos, mas também exige revisão: uma skill não deve conter segredos, comandos destrutivos implícitos ou instruções que ampliem permissões sem explicação.

O suporte a MCP permite conectar ferramentas externas, enquanto os projetos ajudam a separar instruções, documentos e artefatos por contexto. A memória de longo prazo pode guardar fatos ou preferências úteis entre sessões. Para uma equipe, isso traz continuidade; para uma implantação exposta, reforça a necessidade de definir quem pode ler, escrever, importar e apagar dados.

Buscas, RAG e conhecimento privado

O DeerFlow inclui integrações de pesquisa e crawling, além de recuperação de conhecimento privado com RAGFlow. Há suporte e documentação para provedores de busca web e leitura de páginas, incluindo rotas como Jina, Browserless, InfoQuest, Tavily, DuckDuckGo e outros. A disponibilidade real depende da configuração, das chaves, dos limites de cada fornecedor e da política de rede do operador.

Uma pesquisa confiável não nasce apenas por conectar mais buscadores. O agente precisa distinguir fonte primária de opinião, mostrar links, registrar incertezas e não transformar texto recuperado em fato sem checagem. A qualidade do modelo e da skill importa, mas a configuração de ferramentas, timeout, custo, isolamento de rede e rastreabilidade também importam.

Exemplo de uso: pesquisa longa com entrega em arquivos

Um bom primeiro caso de uso é uma pesquisa que normalmente tomaria horas: “compare três ferramentas de atendimento com IA para uma empresa, priorize privacidade e produza um relatório com fontes”. O fluxo saudável seria:

1. definir pergunta, escopo, prazo, idioma e formato do relatório;
2. escolher um modelo e um provedor de busca compatíveis com o orçamento;
3. permitir ao agente usar leitura web e escrita em uma pasta de saída isolada;
4. delegar coleta de fontes, comparação de preços e auditoria de segurança a subagentes;
5. pedir que o agente principal concilie divergências e cite a origem de cada afirmação;
6. revisar os arquivos produzidos antes de compartilhar o resultado.

Esse exemplo mostra por que o DeerFlow não é apenas uma interface de chat. O resultado pode incluir uma conversa, um relatório, planilhas, evidências, logs e arquivos. Por isso, a revisão humana deve ocorrer antes de qualquer decisão financeira, jurídica, operacional ou de segurança.

Diagnóstico e atualização

Antes de abrir uma issue ou reiniciar componentes aleatoriamente, use o diagnóstico:

make doctor

Para problemas locais ou de runtime, o projeto também fornece:

make support-bundle

Segundo a documentação, esse fluxo cria um resumo para issue, um rascunho para abertura assistida e, opcionalmente, um pacote de evidências em .deer-flow/support-bundles/. O bundle busca remover dados sensíveis e não inclui .env, mensagens brutas ou conteúdo de arquivo do usuário; ainda assim, revise qualquer arquivo antes de enviar a terceiros.

Ao atualizar, preserve config.yaml, .env e extensions_config.json. O fluxo indicado é interromper os serviços em uso, rodar git pull --ff-only e iniciar o mesmo modo novamente. Não trate uma atualização de código como motivo para regenerar configuração. Se uma nova versão exigir migração, use make config-upgrade antes de reiniciar.

Vale a pena usar?

DeerFlow faz sentido para quem precisa de agentes com continuidade, ferramentas, arquivos, delegação e controle operacional em vez de uma conversa pontual. Ele pode ser especialmente útil para equipes que já trabalham com automação, pesquisa, desenvolvimento ou relatórios recorrentes e aceitam operar um stack com modelos, banco, Docker e regras de segurança.

Não é a escolha mais simples para quem quer apenas fazer perguntas a um LLM. A instalação consome recursos, os modelos podem gerar custo e as capacidades de sandbox, browser e mensageria exigem administração responsável. Na análise do NoticIA, o diferencial não é “ter muitos agentes”, mas conseguir determinar quais deles podem agir, com quais dados, em qual ambiente e com qual registro de resultado.