DeerFlow: Super Agent Harness Mã Nguồn Mở
DeerFlow là một super agent harness mã nguồn mở của ByteDance, điều phối sub-agent, memory và sandbox cho các tác vụ AI dài hơi, kéo dài từ vài phút đến vài giờ. Nên dùng nếu bạn muốn một stack tự host với checkpoint theo LangGraph và một đường production thật sự qua Postgres và Redis. Nên bỏ qua nếu bạn chỉ cần một chatbot single-agent đơn giản — các chế độ sandbox và cơ chế điều phối worker ở đây là thừa cho nhu cầu đó.
Một Super Agent Harness Mã Nguồn Mở
DeerFlow (Deep Exploration and Efficient Research Flow) là một super agent harness mã nguồn mở do ByteDance xây dựng, điều phối sub-agent, memory và sandbox để research, code và tạo ra sản phẩm. Bản 2.0 là một bản viết lại hoàn toàn, không dùng chung code với framework Deep Research v1 gốc — bản v1 hiện được duy trì trên branch 1.x. DeerFlow chạy dưới dạng một Gateway API cùng frontend web, tích hợp sẵn checkpoint theo LangGraph.
Năng Lực Cốt Lõi và Tích Hợp
- ✓Một Gateway API giữ trạng thái run trong process và expose các endpoint tương thích LangGraph tại `/api/langgraph/*`, được dịch sang route `/api/*` gốc của DeerFlow đằng sau nginx.
- ✓Linh hoạt provider trong một file `config.yaml`: model kiểu OpenAI qua `langchain_openai:ChatOpenAI`, OpenRouter và các gateway tương thích OpenAI khác qua `base_url`, vLLM 0.19.0 qua `deerflow.models.vllm_provider:VllmChatModel`, và xác thực qua CLI cho Codex CLI và Claude Code.
- ✓Thực thi trong sandbox với quyền bash và ghi file được bật/tắt lúc setup, kể cả chế độ provisioner cho sandbox backend dùng chung kiểu AIO.
- ✓Checkpoint theo LangGraph trên SQLite hoặc Postgres, cùng một checkpoint cache tùy chọn ở chế độ delta (in-memory hoặc Redis) cho lịch sử đã materialize.
- ✓Một đường multi-worker được tài liệu hóa cho production: Redis stream bridge, lease run-ownership dựa trên heartbeat, và SSE replay phát ra event `gap` thay vì âm thầm bỏ sót message.
- ✓InfoQuest, bộ công cụ search và crawl do BytePlus xây dựng, được tích hợp cho việc research web, tách biệt với web search provider tùy chọn bạn tự cấu hình.
- ✓Hệ thống skill dựa trên một thư mục `skills/` thuần túy (di chuyển được qua `DEER_FLOW_SKILLS_PATH`), là cách sub-agent có thêm năng lực mới mà không cần sửa code của harness.
- ✓LLM Space, một desktop app riêng để prototype ý tưởng agent, xem từng bước chạy của harness, replay lỗi, và benchmark hiệu năng.
Bắt Đầu với DeerFlow
Clone repo bằng `git clone https://github.com/bytedance/deer-flow.git && cd deer-flow`, sau đó chạy `make setup`. Lệnh này mở một wizard tương tác — chọn LLM provider, quyết định có cấu hình web search provider hay không, và đặt sandbox mode, quyền bash, quyền ghi file — rồi sinh ra một `config.yaml` tối giản cùng key trong `.env`, mất khoảng hai phút. Chạy `make doctor` bất cứ lúc nào để kiểm tra setup và nhận gợi ý sửa lỗi. Nếu muốn cấu hình đầy đủ thay vì file tối giản của wizard, chạy `make config` để copy template đầy đủ, trong đó có tài liệu về CLI-backed provider (Codex CLI, Claude Code OAuth), OpenRouter, OpenAI Responses API, và giới hạn runtime cho subagent như `subagents.max_total_per_run`. Với Docker, `make docker-init` pull sandbox image một lần, rồi `make docker-start` khởi động stack có hot-reload; `make docker-logs` để xem log. Với local development (không Docker), chạy `make check` trước để xác nhận có Node.js 22+, pnpm, uv, nginx, rồi `make install` để cài dependency backend/frontend và pre-commit hook, rồi `make dev`. Trên Windows, chạy flow local từ Git Bash — cmd.exe và PowerShell gốc không được hỗ trợ cho các service script dựa trên bash, và WSL không được đảm bảo hoạt động.
Chạy DeerFlow: Các Tùy Chọn Deployment
Cho development, Docker là hướng README khuyến nghị: `make docker-init` một lần, rồi `make docker-start` để có stack hot-reload, hoặc chạy `./scripts/serve.sh --dev` / `make dev` ở local sau các bước cài đặt ở trên. Khuyến nghị cấu hình từ README: local evaluation cần tối thiểu 4 vCPU / 8 GB RAM / 20 GB SSD trống (khuyến nghị 8 vCPU / 16 GB RAM); Docker development cần tối thiểu 4 vCPU / 8 GB RAM / 25 GB SSD trống (khuyến nghị 8 vCPU / 16 GB RAM). Cho production, `make up` build image tại chỗ và khởi động toàn bộ service, truy cập tại http://localhost:2026; `make down` dừng và xóa container. Một server chạy dài hơi nên bắt đầu ở mức 8 vCPU / 16 GB RAM / 40 GB SSD trống và scale lên 16 vCPU / 32 GB RAM cho use case dùng chung hoặc nhiều agent. Deployment lâu dài cần đặt `database.backend` là `sqlite` hoặc `postgres`, dùng chung cho LangGraph checkpointer, LangGraph Store, và data riêng của DeerFlow. Production mặc định chỉ chạy một Gateway worker (`GATEWAY_WORKERS=1`); chạy nhiều hơn một cần Postgres, Redis stream bridge (`stream_bridge.type: redis`), `run_ownership.heartbeat_enabled: true`, và `run_events.backend: db`.
Điểm Mạnh
- ✓Wizard `make setup` bao quát LLM provider, web search, và quyền sandbox/bash/ghi file trong khoảng hai phút, còn `make doctor` đưa ra gợi ý sửa lỗi cụ thể thay vì chỉ báo fail.
- ✓Sửa `config.yaml` được áp dụng ngay ở lần truy cập tiếp theo mà không cần restart — chỉ có hai setting checkpoint-storage bị đóng băng theo từng process, đó là chủ đích thiết kế.
- ✓Multi-worker production là một setup thật sự, có tài liệu (Redis stream bridge, lease heartbeat, SSE event `gap` kèm replay), chứ không phải một edge case không được hỗ trợ.
- ✓Provider support trải rộng từ API hosted, OpenRouter, vLLM tự host, đến xác thực qua CLI cho Codex CLI và Claude Code, tất cả trong một file config.
- ✓Giấy phép MIT, nên không có ràng buộc copyleft nếu bạn tích hợp DeerFlow vào sản phẩm thương mại.
Các Cân Nhắc Khi Deploy và Yêu Cầu Nâng Cao
- △Mặc định chỉ có một Gateway worker chạy trong production (`GATEWAY_WORKERS=1`); scale vượt quá mức đó cần thêm Postgres, Redis stream bridge, và lease run-ownership dựa trên heartbeat, chứ không chỉ đơn giản thêm replica.
- △Cấu hình sizing khuyến nghị cho server chạy dài hơi bắt đầu ở 8 vCPU / 16 GB RAM / 40 GB SSD trống và tăng lên 16 vCPU / 32 GB RAM cho use case dùng chung — không phải thứ chạy tùy tiện trên một VPS nhỏ.
- △macOS và Windows chỉ được định vị là môi trường development/evaluation; Linux cộng Docker là target khuyến nghị cho một server chạy dài hạn.
- △Local development trên Windows cần Git Bash cụ thể — cmd.exe/PowerShell gốc không được hỗ trợ cho các service script, và hỗ trợ WSL không được đảm bảo.
- △Bản 2.0 không dùng chung code với v1, nên bất cứ thứ gì xây trên framework Deep Research gốc đều không mang sang được — codebase đó giờ bị đóng băng trên branch 1.x.
So Sánh Các Agent Framework
Câu Hỏi Thường Gặp
DeerFlow phát hành theo giấy phép MIT, cho phép bạn dùng, sửa đổi, và phân phối lại, kể cả trong sản phẩm thương mại, mà không có ràng buộc copyleft.
DeerFlow hỗ trợ model kiểu OpenAI qua `langchain_openai:ChatOpenAI`, OpenRouter và các gateway tương thích OpenAI khác, deployment vLLM 0.19.0, và các provider xác thực qua CLI như Codex CLI và Claude Code OAuth, tất cả khai báo trong `config.yaml`.
DeerFlow hỗ trợ development ở local qua `make dev`, chạy Gateway và frontend với hot-reload sau khi `make check` và `make install`; app truy cập được tại http://localhost:2026.
Với local evaluation, README của DeerFlow khuyến nghị 8 vCPU và 16 GB RAM (tối thiểu 4 vCPU/8 GB, 20 GB SSD trống); target cho server chạy dài hạn là 16 vCPU và 32 GB RAM (điểm khởi đầu 8 vCPU/16 GB, 40 GB SSD trống).
DeerFlow hỗ trợ deployment multi-worker nhưng cần Postgres, Redis stream bridge, run-ownership bật heartbeat, và run-events lưu ở database — chế độ single-worker mặc định (`GATEWAY_WORKERS=1`) không thể scale chỉ bằng cách thêm replica.
DeerFlow tích hợp InfoQuest, bộ công cụ search và crawl thông minh do BytePlus xây dựng, và còn cho phép cấu hình riêng một web search provider tùy chọn trong wizard `make setup`.
Vấn đề mà nó giải quyết
Các tác vụ agent dài hơi — loại research một chủ đề, viết code, và tạo ra kết quả trong vài phút đến vài giờ thay vì một lần request/response — cần nhiều hơn một vòng lặp chat: cần sandbox để code do agent sinh ra không đụng vào host, cần memory xuyên suốt các bước, và cần cách phục hồi sạch sẽ khi một worker chết giữa chừng. DeerFlow gói các phần này (sub-agent, sandbox, memory, một message gateway) vào một harness duy nhất, thay vì để bạn tự nối một checkpoint store, một sandbox provider, và một hệ thống run-ownership/lease lại với nhau.
Use Case Phù Hợp Nhất
- •Agent research dài hơi cần sống sót qua các run kéo dài vài phút đến vài giờ mà không mất trạng thái nếu một worker restart.
- •Agent code cần quyền bash và ghi file thật sự trong sandbox, không chỉ gợi ý code kiểu chat.
- •Team đã dùng LangGraph/LangChain muốn sandbox, memory, và điều phối multi-agent được đóng gói sẵn thay vì tự nối từ các thư viện riêng lẻ.
- •Workflow agent xoay quanh search và crawl kiểu InfoQuest thay vì một API search hosted đơn lẻ.
- •Prototype các bước của harness ở local bằng LLM Space trước khi đưa thay đổi lên Gateway production.
Nên Dùng — và Nên Bỏ Qua Khi Nào
Nên thử DeerFlow nếu bạn đang xây một sản phẩm agent dài hơi — biết plan, code, và research trong các run kéo dài vài phút đến vài giờ — và bạn không ngại tự vận hành một Gateway API, sandbox container, và checkpoint database. Nó hợp với team đã dùng LangGraph/LangChain muốn có sẵn phần sandbox, memory, và điều phối thay vì tự nối tay. Nên bỏ qua nếu bạn muốn một sản phẩm agent hosted, zero-ops, hoặc workload của bạn chỉ là một lệnh gọi LLM ngắn không cần sub-agent, sandbox, hay memory bền vững — wizard cài đặt và yêu cầu sizing ở đây sẽ không đáng công.