Tutorial de Introdução ao DeerFlow 2.0: Construindo seu Primeiro Workstation de AI Agent Passo a Passo

Dificuldade: Iniciante | Duração: 15 minutos | Resultado: Construção de um assistente de IA executável do zero

Você já imaginou como seria ter um assistente de IA que não apenas responde a perguntas, mas que pode realmente operar seu computador, escrever código, pesquisar informações e até gerar relatórios completos? Hoje vamos apresentar o DeerFlow, um AI Agent capaz de trabalhar para você.

Público-Alvo

Desenvolvedores Backend/Fullstack de 1 a 3 anos de experiência
Interessados em AI Agents que não sabem por onde começar
Quem deseja hospedar suas próprias ferramentas de IA, mas se preocupa com os custos

Dependências Core e Ambiente

Antes de começar, certifique-se de que seu ambiente de desenvolvimento atende aos seguintes requisitos:

Node.js: 22.x ou superior
pnpm: 9.x ou superior
Docker: última versão estável
Git: para clonar o projeto

[!TIP]
Recomenda-se o uso do Docker para implantação: inicialização com um clique, sem necessidade de configurar manualmente serviços como Nginx.

Estrutura Completa do Projeto

Após a instalação, você verá a seguinte estrutura de arquivos:

deer-flow/
├── backend/                    # Serviço backend
│   ├── src/
│   │   ├── client.py           # Cliente Python
│   │   ├── agent/              # Core do Agent
│   │   └── skills/            # Skills integradas
│   └── docs/                   # Documentação de configuração
├── frontend/                   # Interface Web
├── config.yaml                 # Arquivo de configuração de modelos
├── .env                        # Variáveis de ambiente
└── Makefile                    # Comandos de inicialização

Passo a Passo

Passo 1: Clonar o Projeto

Abra o terminal e execute os seguintes comandos:

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

[!TIP]
Se tiver dificuldades para acessar o GitHub, considere usar um mirror ou baixar diretamente o arquivo compactado da versão Release.

Passo 2: Gerar os Arquivos de Configuração

O DeerFlow oferece comandos de geração de configuração que criam arquivos locais baseados em templates:

make config

Após a execução, você verá os arquivos config.yaml e .env na raiz do projeto.

Passo 3: Configurar Modelos (Importante!)

Este é o passo mais crucial. O DeerFlow suporta vários provedores de modelos, mas recomendamos fortemente o uso do Defapi, por um motivo simples: o preço é metade do oficial.

[!WARNING]
Se você usar diretamente a API oficial da OpenAI, os custos mensais podem facilmente ultrapassar centenas de dólares. Usar o Defapi pode reduzir esse custo pela metade ou mais.

Abra o config.yaml e configure-o da seguinte forma:

models:
  - name: gpt-4o-mini              # Identificador interno
    display_name: GPT-4o Mini      # Nome de exibição
    use: langchain_openai:ChatOpenAI
    model: openai/gpt-4o-mini      # Identificador de modelo Defapi
    api_key: $DEFAPI_API_KEY       # Usa variável de ambiente
    base_url: https://api.defapi.org  # Endpoint Defapi
    max_tokens: 4096
    temperature: 0.7
    supports_vision: true

Em seguida, insira sua API Key do Defapi no arquivo .env:

DEFAPI_API_KEY="dk-xxxxxxxxxxxxxxxx"
TAVILY_API_KEY="your-tavily-api-key"  # Necessário para busca na web

[!TIP]
Acesse https://defapi.org para registrar uma conta; novos usuários geralmente possuem saldo gratuito para experimentação.

Modelos populares suportados pelo Defapi:

Modelo	Identificador	Cenário de Uso
GPT-4o Mini	openai/gpt-4o-mini	Diálogos diários, alto custo-benefício
GPT-4o	openai/gpt-4o	Tarefas complexas, escolha equilibrada
Claude Sonnet 4.5	anthropic/claude-sonnet-4.5	Forte capacidade de programação
DeepSeek V3	deepseek/deepseek-v3	Forte raciocínio, preço econômico

Passo 4: Baixar a Imagem do Sandbox

Antes de rodar via Docker, você precisa baixar a imagem do sandbox (este passo é executado apenas uma vez):

make docker-init

A imagem é grande, então pode levar alguns minutos dependendo da sua conexão.

Passo 5: Iniciar os Serviços

Com tudo pronto, inicie o DeerFlow:

make docker-start

Quando vir uma saída semelhante a esta, significa que a inicialização foi bem-sucedida:

✔ Frontend started on http://localhost:2026
✔ Backend started on http://localhost:8000

Passo 6: Acessar a Interface

Abra o navegador e acesse http://localhost:2026. Você verá uma interface de chat moderna.

Passo 7: Sua Primeira Tarefa

No campo de chat, digite:

Olá, por favor, apresente-se.

Você notará que o DeerFlow não apenas responderá, mas também dirá quais capacidades ele possui:

Pesquisa na web
Leitura e escrita de arquivos
Execução de comandos
Geração de relatórios, slides e páginas web

Tente agora uma tarefa mais desafiadora:

Por favor, liste a estrutura de arquivos do diretório atual.

O DeerFlow executará o comando no ambiente sandbox e retornará o resultado. Esta é a diferença fundamental entre ele e um chatbot comum — ele realmente pode realizar o trabalho por você.

Solução de Problemas Comuns

Q1: Falha ao iniciar container, erro de porta ocupada

# Verifique qual processo está usando a porta 2026
lsof -i :2026
# Ou no Windows
netstat -ano | findstr 2026

Encerre o processo encontrado ou altere a porta no config.yaml.

Q2: API Key configurada corretamente, mas ainda ocorre erro

Verifique se o arquivo .env está na raiz do projeto e se você executou source .env ou reiniciou os containers.

Q3: O modelo não suporta chamadas de ferramentas (tool calling)

Alguns modelos não suportam function calling. Certifique-se de usar modelos como GPT-4o, Claude ou Gemini que suportam essa funcionalidade. Os modelos fornecidos pelo Defapi são compatíveis com o protocolo OpenAI e geralmente funcionam sem problemas.

Q4: A busca na web retorna resultados vazios

Verifique se o TAVILY_API_KEY está configurado corretamente. Tavily é o provedor de busca padrão do DeerFlow.

Q5: Memória insuficiente no Docker

A memória padrão do Docker pode não ser suficiente. Recomenda-se configurar 4GB ou mais:

// Docker Desktop -> Settings -> Resources

Direções Avançadas

1. Customização de Skills

O sistema de Skills do DeerFlow é altamente flexível. Você pode criar seu próprio Skill:

/mnt/skills/custom/
└── my-awesome-skill/
    └── SKILL.md

Basta seguir o formato de Markdown das Skills integradas para escrever a sua.

2. Extensão via Servidor MCP

O DeerFlow suporta o protocolo MCP, permitindo a conexão com várias ferramentas externas. Veja mais no guia oficial MCP Server Guide.

3. Alternar para outros modelos

Se quiser experimentar o DeepSeek ou Claude, basta modificar o config.yaml:

# Exemplo de configuração DeepSeek
models:
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: langchain_openai:ChatOpenAI
    model: deepseek/deepseek-v3
    api_key: $DEFAPI_API_KEY
    base_url: https://api.defapi.org
    supports_thinking: true

4. Uso do Cliente Python Embutido

O DeerFlow também fornece uma biblioteca Python para ser integrada diretamente em seu projeto:

from src.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("Analise este artigo", thread_id="meu-topico")

# Saída em streaming
for event in client.stream("olá"):
    print(event.data)

Conclusão

Hoje montamos juntos o DeerFlow 2.0, desde a preparação do ambiente até a execução da primeira tarefa. Você percebeu que este não é apenas um chatbot, mas um workstation de IA real que ajuda na produtividade.

As principais vantagens do DeerFlow são:

Extensível: Suporta customização de Skills, MCP e Sub-Agents.
Seguro e Controlado: Isolamento por sandbox, as tarefas rodam em containers Docker.
Custos Flexíveis: Através do Defapi, os custos podem ser reduzidos significativamente em relação aos preços oficiais.

Vá em frente e experimente! Deixe que ele escreva código, pesquise informações e gere relatórios para você. Você descobrirá novas formas de utilizar a IA.

Se encontrar problemas durante a montagem, deixe um comentário e tentarei ajudar. Na próxima vez, falaremos profundamente sobre como customizar Skills para o DeerFlow realizar tarefas específicas.

Divirta-se!