DeerFlow 2.0: harness siêu agent với sandbox, sub-agent và bộ nhớ dài hạn
Đăng ngày 12/10/2026
Mục lục bài nghiên cứu
DeerFlow 2.0 trong một trang: khi nào nên dùng, khi nào nên tránh
DeerFlow (Deep Exploration and Efficient Research Flow) là một super agent harness mã nguồn mở của ByteDance: lớp hạ tầng để agent, tức chương trình dùng mô hình ngôn ngữ tự lập kế hoạch và gọi công cụ, làm việc cùng sub-agent (agent con nhận việc được giao), bộ nhớ dài hạn và sandbox (môi trường thực thi cách ly), mở rộng bằng skill. Bản 2.0 được viết lại từ đầu trên LangGraph và LangChain, không chung mã với nhánh 1.x. [1][3]
Khác một thư viện agent thuần, DeerFlow kèm sẵn ứng dụng có giao diện web, Gateway API, tác vụ định lịch và kênh nhắn tin, có thể tự host; lõi Harness cũng dùng riêng được như một SDK Python. [1][7]
Nên cân nhắc khi công việc kéo dài nhiều bước: đọc tài liệu tải lên, chạy phân tích trong môi trường cách ly, trả về báo cáo hay bảng tính. Nên tránh nếu chỉ cần hỏi đáp ngắn, nếu không có người vận hành Linux và Docker, hoặc nếu phải mở ra Internet khi chưa có lớp xác thực, vì cấu hình mặc định dành cho môi trường tin cậy cục bộ. [1]
Khoảng trống giữa chatbot có công cụ và agent làm việc nhiều giờ
Gắn công cụ vào chatbot không khó; khó là giữ agent làm việc qua hàng chục bước khi ngữ cảnh đầy dần, tệp trung gian không có chỗ lưu và quyền chạy lệnh trở thành rủi ro. Theo README, cộng đồng đã dùng DeerFlow vượt khỏi nghiên cứu, sang pipeline dữ liệu, slide, dashboard, nên nhóm phát triển viết lại nó thành harness, tức runtime cung cấp hạ tầng để agent hoàn thành việc. [1]
Câu hỏi trung tâm vì thế là agent làm việc trong điều kiện nào: thư mục riêng cho từng luồng hội thoại, chỗ cho đầu vào và đầu ra, cơ chế tóm tắt và đẩy kết quả trung gian ra hệ thống tệp, khả năng giao việc cho agent con có ngữ cảnh tách biệt. [1]
Mặt trái là kiểm soát: agent chạy được shell và gọi dịch vụ ngoài thì cũng gây được hậu quả ngoài ý muốn. Việc đánh giá vì vậy phải trả lời ba câu: thực thi được cô lập thế nào, quyền được giới hạn bằng cơ chế gì, và hệ thống để lại dấu vết nào.
Kiến trúc bốn dịch vụ và lõi Harness tách khỏi App
Khi chạy bằng make dev hoặc Docker, DeerFlow gồm bốn dịch vụ: Nginx cổng 2026 là lối vào công khai duy nhất; Gateway API cổng 8001 là ứng dụng FastAPI nhúng runtime agent tương thích LangGraph; frontend Next.js cổng 3000; provisioner cổng 8002 chỉ dùng khi sandbox chạy trên Kubernetes. Nhờ Nginx chuyển /api/langgraph/* tới runtime, client dùng SDK LangGraph không cần máy chủ LangGraph riêng. [3][4]
Backend chia hai lớp phụ thuộc một chiều: Harness, gói deerflow chứa điều phối, công cụ, sandbox, mô hình, MCP, skill và bộ nhớ; App, gồm FastAPI Gateway và tích hợp kênh nhắn tin. App được nhập Harness, còn chiều ngược lại bị CI chặn. [3]
Lead agent do make_lead_agent() lắp ráp, bọc trong chuỗi middleware, tức các lớp xử lý chen trước và sau lời gọi mô hình, lo thư mục thread, tệp tải lên, cấp sandbox, tóm tắt ngữ cảnh, đặt tiêu đề, danh sách việc, ảnh và câu hỏi làm rõ. [3][4] SandboxProvider có hai hiện thực chính: LocalSandboxProvider chạy thẳng trên máy chủ cho phát triển, AioSandboxProvider chạy trong container Docker; agent chỉ thấy đường dẫn ảo như /mnt/user-data/outputs. [4] Hướng dẫn triển khai bổ sung E2B và AIO kèm provisioner Kubernetes. [6]
Hành trình của một yêu cầu: từ tệp tải lên tới thư mục outputs
Một yêu cầu bắt đầu bằng POST tới /api/langgraph/threads/{thread_id}/runs. Gateway nạp hoặc tạo trạng thái thread, chạy chuỗi middleware, để mô hình xử lý và gọi công cụ như bash hay web_search qua sandbox, rồi stream phản hồi bằng SSE (Server-Sent Events, kênh đẩy sự kiện một chiều qua HTTP). [4]
Tệp tải lên được kiểm tra, lưu vào thư mục uploads của thread và chuyển sang Markdown bằng markitdown khi là tài liệu; lượt sau, UploadsMiddleware đưa danh sách tệp vào ngữ cảnh. [4] Ở chiều ra, khi run tạo hoặc sửa tệp dưới /mnt/user-data/outputs, Gateway buộc present_files trình bày ít nhất một đầu ra và ghi bền biên nhận run.delivery, kèm tóm tắt tệp được tạo, sửa, xóa. [1]
DeerMem, bộ nhớ dài hạn mặc định, lấy đầu vào người dùng và câu trả lời cuối của agent, gom cập nhật sau khoảng lặng mặc định 30 giây. [1] Dữ liệu thread nằm dưới backend/.deer-flow/threads và bị xóa cùng hội thoại; production chạy Docker nên dùng named volume hoặc PVC. [4][6] Đây là chỗ phải tính sao lưu, mã hóa ổ đĩa và thời hạn lưu giữ.
Năng lực đã đối chiếu: skill, sub-agent, bộ nhớ, lịch chạy và kênh nhắn tin
Skill là tệp SKILL.md mô tả quy trình và tài nguyên; DeerFlow có sẵn skill nghiên cứu, viết báo cáo, làm slide, trang web, sinh ảnh và video, chỉ nạp khi cần. [1] Công cụ lõi gồm tìm kiếm web, tải trang, chụp trang, thao tác tệp và bash; công cụ tùy biến thêm qua MCP (Model Context Protocol, giao thức nối công cụ với mô hình) hoặc hàm Python. [1][4]
Lead agent sinh sub-agent có ngữ cảnh, công cụ và điều kiện dừng riêng khi lợi ích về song song, chuyên môn hay tách ngữ cảnh là rõ; README nhấn mạnh sub-agent là tối ưu hóa, không phải phản xạ mặc định. batch_task lưu lô hạng mục độc lập trong SQL, khôi phục được sau khởi động lại. [1]
Projects gom hội thoại dưới chỉ dẫn và kệ tài liệu chung; RAGFlow, nếu bật, cho câu trả lời trích dẫn đoạn trích kèm số trang khi có, mà không lộ khóa API cho mô hình; bộ nhớ có thêm các backend tùy chọn mem0, Honcho, OpenViking. [1]
Tác vụ định lịch hỗ trợ một lần, cron và chu kỳ, mặc định tối đa hai run đồng thời mỗi chủ sở hữu. Kênh nhắn tin gồm Telegram, Slack, Feishu/Lark, WeChat, WeCom, QQ, DingTalk, Buzz, không cần IP công khai nhưng không có Zalo; giao diện dòng lệnh deerflow chạy được không cần Gateway. [1]
Skill, MCP và extension: ba cửa mở rộng, ba mức tin cậy
DeerFlow có ba cửa mở rộng với mức đặc quyền khác nhau: skill là văn bản hướng dẫn kèm script; MCP server là tiến trình công cụ bên ngoài; extension là gói Python nạp vào Gateway qua mục plugins của config.yaml, thêm được middleware, dịch vụ, router HTTP, và chạy với đặc quyền của Gateway. [1]
Theo dự án, allowed-tools của skill chỉ là giới hạn hành vi theo kiểu cố gắng tối đa, không phải ranh giới bảo mật cứng; mỗi lần cài hoặc sửa skill đều qua SkillScan, bộ quét tất định chặn phát hiện nghiêm trọng như khóa riêng tư hay lệnh shell. [1] MCP server dạng stdio chạy lệnh trong container Gateway, giới hạn ở danh sách cho phép (mặc định npx, uvx), nhưng quyền admin Gateway vẫn tương đương quyền thực thi mã trên máy chủ. [1]
Hệ quả quản trị: config.yaml, extensions_config.json, thư mục skills và danh sách plugin cần được quản lý như mã nguồn, có người duyệt thay đổi, có lịch sử phiên bản và chỉ ít người có quyền ghi.
Đối tượng nên đưa DeerFlow vào danh sách đánh giá
Phù hợp nhất là đội dữ liệu, đội nghiên cứu hoặc bộ phận vận hành nội bộ có việc tổng hợp dài hơi: đọc nhiều tài liệu, chạy phân tích, bàn giao tệp. Đây là suy luận từ năng lực được mô tả, không phải danh sách tổ chức đang dùng DeerFlow.
Nhà phát triển muốn tự xây sản phẩm agent nên bắt đầu từ Harness: tài liệu khái niệm gợi ý chọn Harness để dựng hệ thống riêng, chọn App khi cần một sản phẩm hoàn chỉnh, hoặc dùng cả hai. [7] DeerFlowClient trả về cùng lược đồ dữ liệu với HTTP Gateway, tiện khi nhúng vào hệ thống sẵn có. [1]
Không phù hợp với tổ chức thiếu người quản trị Linux, Docker hay cần phản hồi tức thời; trên Windows, phát triển cục bộ phải chạy qua Git Bash. [1] Một kho tri thức cá nhân kiểu bộ não thứ hai, như kho nghiên cứu của phamvanthu.com, có thể tham khảo cách DeerFlow tách thread, outputs và kệ tài liệu dự án; bài không khẳng định website hay BDSG đang dùng DeerFlow.
Tình huống giả định: phòng merchandising của nhà máy may xuất khẩu
Giả định một nhà máy may ở Bình Dương khoảng 1.500 công nhân, làm hàng cho ba nhãn thời trang châu Âu và Nhật Bản. Mỗi tuần, phòng merchandising 12 người đọc tech pack (hồ sơ kỹ thuật của mẫu hàng), sổ tay tuân thủ của khách, đối chiếu với tiến độ nguyên phụ liệu để báo cáo tình trạng đơn hàng. Kịch bản chỉ mang tính minh họa.
Đề xuất: mỗi khách hàng là một Project, chỉ dẫn dự án ghi quy tắc riêng như đơn vị đo, mã hàng, ngưỡng cảnh báo trễ vải, kệ tài liệu chứa sổ tay tuân thủ và mẫu báo cáo. [1] Agent đọc kế hoạch Excel, tech pack PDF trong sandbox Docker, so ngày xuất hàng với ngày về nguyên liệu và ghi báo cáo vào outputs; tác vụ định lịch sáng thứ Hai tạo bản nháp. [1][4]
Ràng buộc: Zalo không có trong danh sách kênh, và extension chưa được mở endpoint không xác thực để nhận webhook. [1] Vì vậy nên bắt đầu bằng giao diện web nội bộ; muốn đẩy thông báo, đội IT tự viết dịch vụ cầu nối gọi Gateway API bằng personal access token, loại token chỉ vào được route vòng đời thread và run. [1]
Tech pack và giá gia công thường thuộc thỏa thuận bảo mật, nên ưu tiên mô hình tự host qua vLLM, cấu hình DeerFlow hỗ trợ, hoặc nhà cung cấp đã cam kết xử lý dữ liệu. [1] Dữ liệu cá nhân công nhân nằm ngoài phạm vi; mọi báo cáo phải qua merchandiser phụ trách trước khi gửi khách.
Triển khai và vận hành: cỡ máy, cơ sở dữ liệu, nâng cấp
README đưa bảng cỡ máy: đánh giá cục bộ khởi điểm 4 vCPU, 8 GB RAM, 20 GB SSD; máy chủ chạy lâu dài khởi điểm 8 vCPU, 16 GB RAM, 40 GB SSD, khuyến nghị 16 vCPU và 32 GB; các con số chưa tính mô hình tự host, và Linux kèm Docker là đích khuyến nghị. [1] Mỗi phiên sandbox cần tối thiểu 1 vCPU và 1 GB RAM. [6]
SQLite chỉ cho một tiến trình ghi tại một thời điểm, dễ gây lỗi database is locked khi nhiều người cùng chạy agent, nên môi trường nhiều người dùng cần Postgres. [6] Nhiều bản sao Gateway còn cần Redis cho stream bridge, heartbeat sở hữu run và lưu sự kiện trong cơ sở dữ liệu; kênh nhắn tin và công cụ trình duyệt vẫn chỉ chạy một bản sao. [1][6]
Lệnh make doctor kiểm tra cấu hình; make support-bundle tạo gói chẩn đoán không chứa .env, nội dung hội thoại hay tệp người dùng. Khi nâng cấp, giữ config.yaml, .env, extensions_config.json, chạy git pull --ff-only rồi make config-upgrade nếu cần; chuyển kho bộ nhớ từ v1 sang v2 là một chiều nên phải sao lưu trước. Quan sát dựa trên LangSmith, Langfuse, Monocle và header X-Trace-Id. [1]
Bảo mật: mặc định chỉ tin 127.0.0.1, phần còn lại do người triển khai
README cảnh báo DeerFlow có năng lực đặc quyền cao như thực thi lệnh hệ thống và gọi logic nghiệp vụ, và mặc định dành cho môi trường tin cậy chỉ truy cập qua 127.0.0.1. Chỉ đặt BIND_HOST để mở cho máy khác khi đã có danh sách IP cho phép, reverse proxy xác thực mạnh, VLAN riêng và tài khoản admin được tạo ngay qua /setup. [1][3]
LocalSandboxProvider tắt bash trên máy chủ theo mặc định vì đó không phải ranh giới cách ly an toàn; sandbox AIO trong Docker mặc định vẫn mở kết nối ra ngoài, phải tự chuyển sang isolated hoặc allowlist. [1] Theo tài liệu guardrail, sandbox chỉ cô lập tiến trình, không phân quyền theo ngữ nghĩa: bash trong sandbox vẫn dùng được curl để đẩy dữ liệu ra ngoài. [8]
GuardrailMiddleware đánh giá mọi lời gọi công cụ trước khi thực thi bằng một provider: danh sách cho phép có sẵn, hộ chiếu OAP, mã tự viết, hoặc TypeSafe, provider duy nhất gửi tham số công cụ cho bên thứ ba. Guardrail tắt mặc định; khi bật, lỗi provider dẫn tới chặn lời gọi. [8] Lớp RBAC theo vai trò cũng tắt mặc định. [1]
Che thông tin định danh (pii_redaction) tắt mặc định; trace Monocle ghi nguyên văn prompt và tham số công cụ, exporter từ xa đưa chúng ra khỏi máy; tích hợp Lark mount bí mật ứng dụng vào sandbox ở dạng đọc được. [1] Đề xuất: bật guardrail và RBAC trước khi có nhiều người dùng, khóa egress của sandbox, chỉ gửi trace tới hệ thống do tổ chức kiểm soát.
Giấy phép MIT và những gì nằm ngoài phạm vi của nó
LICENSE gốc tại commit là MIT, ghi bản quyền Bytedance Ltd. và các công ty liên kết (2025) cùng DeerFlow Authors (2025–2026); README cũng ghi dự án phát hành theo MIT. [1][2] MIT cho phép dùng, sửa, phân phối, bán lại nếu giữ thông báo bản quyền và giấy phép, và không kèm bảo hành. [2]
Không nên suy rộng MIT cho mọi thư mục: skills/public/frontend-design có LICENSE.txt là văn bản Apache License 2.0, với điều kiện riêng như kèm bản giấy phép và đánh dấu tệp đã sửa. [9] Vài thư mục skill, ví dụ và tài nguyên giao diện khác cũng có tệp giấy phép mà bài chưa đọc, cần rà soát trước khi đóng gói lại.
Về phiên bản, README ghi 2.0 là bản viết lại; SECURITY.md cho biết nhánh main dành cho 2.x và main-1.x cho 1.x, nhưng vẫn ghi dự án chưa có bản phát hành chính thức và khuyên dùng bản mới nhất. [1][5] Vì các tài liệu chưa khớp nhau, tổ chức nên tự chốt một commit hoặc thẻ đã kiểm thử.
MIT không bao trùm các mô hình Doubao, DeepSeek, Kimi mà README giới thiệu, gói Coding Plan của Volcengine, bộ công cụ tìm kiếm InfoQuest của BytePlus, dịch vụ RAGFlow, LangGraph, LangChain hay các phụ thuộc khác. [1]
Chi phí và nguồn lực: máy chủ, token và giờ công
Không có phí giấy phép, nhưng chi phí sở hữu gồm hạ tầng (máy chủ Linux, lưu trữ thread và sandbox), mô hình (API theo token hoặc GPU tự host), nhân sự kỹ thuật và thời gian người duyệt; bài không nêu giá vì giá thay đổi theo nhà cung cấp và thời điểm.
Cơ chế giới hạn chi phí trong tài liệu: recursion_limit mặc định 100 cho run qua Gateway API, trần 1000; request_admission (tùy chọn) điều tiết nhịp gọi theo giới hạn nhà cung cấp; giá theo mô hình khai báo được để ước tính, miễn dùng một loại tiền. Riêng run có mục tiêu, token_budget không phải giới hạn chặt theo tiền; chế độ snapshot của sub-agent tốn thêm token đầu vào. [1]
Giả định cho nhà máy may: một máy chủ ở mức khởi điểm cho chạy lâu dài, một kỹ sư DevOps bán thời gian trong giai đoạn thử, một merchandiser trưởng dành vài giờ mỗi tuần để duyệt và chỉnh skill. Chi phí mô hình nên đo bằng số token trên mỗi báo cáo đạt yêu cầu; nếu tự host mô hình thì cộng thêm máy chủ GPU và công vận hành.
Harness đóng gói sẵn hay tự lắp: so sánh các hướng tiếp cận
Dùng thẳng khung đồ thị như LangGraph cho tự do cao nhất nhưng phải tự xây sandbox, quản lý tệp, giao diện, lịch chạy và phân quyền; DeerFlow là lớp dựng sẵn trên LangGraph và LangChain, nên câu hỏi là có muốn nhận các quyết định thiết kế của nó không. [1][3]
Thư viện agent gọn như CrewAI, AutoGen hay Pydantic AI hợp khi ứng dụng đã có xác thực, dữ liệu và giao diện, chỉ thiếu vòng lặp agent. Dịch vụ agent SaaS khởi động nhanh nhưng dữ liệu đi qua hạ tầng của bên thứ ba. Script hoặc RPA truyền thống rẻ và dễ kiểm soát khi quy trình đã cố định, không cần diễn giải ngôn ngữ.
Tiêu chí đề xuất: chọn DeerFlow khi cần cùng lúc môi trường thực thi, tệp kết quả, nhiều người dùng, lịch chạy và tự host; nếu chỉ cần một hai yếu tố, phương án nhẹ hơn thường ít rủi ro vận hành hơn. Bài không có số liệu hiệu năng so sánh vì không đo.
Giới hạn đọc được từ tài liệu và điều kiện không nên triển khai
README rất dài, trộn hướng dẫn với ghi chú tương thích và hành vi biên, làm tăng chi phí học và rủi ro cấu hình sai. Một số phần còn ở mức MVP hoặc thử nghiệm: tác vụ định lịch chưa có thông báo chỉ văn bản hay đích gửi tới kênh, API trình duyệt cho plugin được ghi là thử nghiệm, và chỉ WeCom nhận được kết quả định lịch đẩy chủ động. [1]
Gateway mặc định một worker vì giữ tác vụ đang chạy trong tiến trình, nên mở rộng ngang là một dự án cấu hình riêng. [1][6] DeerFlow chạy tốt nhất với mô hình có ngữ cảnh từ 100 nghìn token, suy luận tốt, đa phương thức và gọi công cụ ổn định, điều mô hình nhỏ tự host có thể không đáp ứng. [1]
Không nên triển khai khi phải phục vụ người ngoài Internet mà chưa có lớp xác thực đứng trước, khi dữ liệu không được rời nội bộ mà chưa có mô hình nội bộ đủ tốt, khi không ai hiểu YAML, Docker, Postgres, hoặc khi đầu ra dẫn thẳng tới quyết định pháp lý mà không có người duyệt.
Kế hoạch thử nghiệm mười tuần cho phòng merchandising
Tuần 1–2, chuẩn bị: dựng một máy chủ Linux nội bộ chạy Docker, giữ cổng ở loopback và truy cập qua VPN; dùng Postgres nếu có hơn hai người dùng; bật AllowlistProvider chỉ cho đọc tệp, tìm kiếm nội bộ và ghi báo cáo; khóa egress của sandbox. [1][6][8] Chọn 30 bộ hồ sơ đơn hàng đã đóng làm dữ liệu đối chứng.
Tuần 3–6, chạy song song: agent soạn nháp báo cáo tuần cho một khách hàng, merchandiser vẫn làm cách cũ. Chỉ số: tỷ lệ trường đúng so với bản người làm, mục tiêu từ 95% với ngày xuất hàng, số lượng, mã nguyên liệu; lỗi nghiêm trọng bằng 0; thời gian duyệt mỗi báo cáo; token trên mỗi báo cáo đạt yêu cầu; số lần guardrail chặn.
Tuần 7–10, mở rộng có kiểm soát: thêm khách hàng thứ hai và bật tác vụ định lịch. Dừng nếu xảy ra sự cố lộ dữ liệu, nếu tỷ lệ đúng vẫn dưới ngưỡng sau hai vòng chỉnh skill, hoặc nếu thời gian duyệt không thấp hơn thời gian tự làm. Các ngưỡng chỉ là đề xuất để doanh nghiệp tự đặt, tự đo; bài không có dữ liệu thực nghiệm về DeerFlow.
Kết luận: nền tảng mạnh cần người gác cổng rõ ràng
DeerFlow 2.0 gom runtime agent, sandbox, bộ nhớ, giao diện, lịch chạy và kênh nhắn tin vào một kho mã, đồng thời tách được lõi Harness cho người muốn tự xây sản phẩm. [1][7] Giá trị với doanh nghiệp là biến công việc nghiên cứu nhiều bước thành quy trình có thư mục, có tệp kết quả và có dấu vết.
Phạm vi rộng ấy cũng là nguồn rủi ro: quyền chạy lệnh, mở rộng bằng mã và kết nối ra ngoài phải được khóa bằng cấu hình, không trông vào lời dặn trong prompt, và cần một người chịu trách nhiệm trước khi dữ liệu thật đi vào.
Bước kế tiếp hợp lý là chọn một quy trình báo cáo đối chiếu được, dựng trong mạng nội bộ với guardrail bật sẵn, đo theo các tiêu chí đã nêu, và dừng nếu kết quả không vượt cách làm hiện tại.
Cách chọn dự án, commit đã khóa và giới hạn của phương pháp
DeerFlow thuộc nhóm AI agents và ứng dụng, được chọn vì có mặt trong danh sách Python ngày 24/01/2026 của một kho lưu trữ độc lập các trang GitHub Trending; bảng tổng hợp ứng viên của loạt bài ghi lần xuất hiện cuối ngày 30/09/2026. [10] Kho chỉ có danh sách Python, Go, JavaScript, Swift, thiếu ngày 03/09 và 12/10/2026, nên không phải Top 100 chính thức của GitHub.
Đối chiếu dựa trên commit 1f15e0b43ca58b9601514f9f5c408fb032022833 (12/10/2026 theo giờ UTC), kiểm tra ngày 12/10/2026. Bài đã đọc README, LICENSE, SECURITY.md, hai tệp ARCHITECTURE.md, hướng dẫn triển khai, cùng ba tài liệu bổ sung tại cùng commit: trang Harness vs App, backend/docs/GUARDRAILS.md và LICENSE.txt của skill frontend-design. [1][2][3][4][5][6][7][8][9] CHANGELOG.md vượt giới hạn dung lượng của công cụ thu thập nên không được dùng.
Đây là nghiên cứu tài liệu có hỗ trợ AI: không cài đặt, không chạy, không đo hiệu năng, và không phải công bố khoa học đã qua phản biện. Kiến trúc ứng dụng, tình huống Việt Nam, chi phí, so sánh và kế hoạch thử nghiệm là phân tích, đề xuất của bài; số sao hay lời quảng bá không được dùng làm bằng chứng chất lượng.
Xem mã nguồn DeerFlow trên GitHub