DeerFlow 2.0은 ByteDance가 만든 LangGraph 기반 "슈퍼 에이전트 하네스"입니다. 단순 에이전트 라이브러리가 아니라, 에이전트·도구·메모리·샌드박스·스킬·메시징 채널을 총괄하는 통합 런타임입니다. v1.0(Deep Research 프레임워크)에서 v2.0으로 완전 재설계(ground-up rewrite)되어 아키텍처 성숙도가 높습니다. 2026년 2월 28일 GitHub Trending 1위 달성 후 폭발적으로 성장했습니다.
LangGraph가 바이올린·첼로·피아노(에이전트 로직)를 만드는 악기라면, DeerFlow는 전체 오케스트라를 지휘하는 공연장입니다. 무대(샌드박스), 악보(스킬), 방음실(메모리), 통신(IM 채널)까지 공연에 필요한 모든 것을 갖춥니다.
특히 다수의 미들웨어(15개+)가 파이프라인으로 순차 실행되는 구조가 핵심입니다. 각 미들웨어가 관심사를 분리하여 코어를 건드리지 않고 기능을 추가·제거할 수 있습니다.
1. 하네스 개념: 에이전트·도구·메모리·샌드박스·스킬을 총괄하는 통합 런타임. 단순 프레임워크보다 상위 개념.
2. 미들웨어 체인: 다수의 미들웨어(15개+)가 파이프라인으로 동작 — 관심사 분리가 극도로 깔끔.
3. Harness/App 분리: 에이전트 코어(deerflow-harness)와 애플리케이션(app)의 경계를 CI 테스트로 강제.
| 비교 항목 | DeerFlow 2.0 | AutoGen | CrewAI | LangGraph 단독 |
|---|---|---|---|---|
| 서브에이전트 오케스트레이션 | 내장 (리드→서브 위임) | 멀티에이전트 대화 | 크루/태스크 기반 | 직접 구현 필요 |
| 샌드박스 격리 | Docker/K8s 네이티브 | 제한적 | 없음 | 없음 |
| 퍼시스턴트 메모리 | LLM 기반 팩트 추출 + JSON | 제한적 | 없음 | 직접 구현 |
| MCP 통합 | OAuth 포함 다중 서버 | 없음 | 없음 | 없음 |
| 스킬 시스템 | 마크다운 기반 프로그레시브 로딩 | 없음 | 없음 | 없음 |
| IM 채널 통합 | 7개 채널 (Telegram/Slack/Feishu/Discord/DingTalk/WeCom/WeChat) | 없음 | 없음 | 없음 |
| 프론트엔드 | Next.js 풀스택 웹 UI | 별도 | 없음 | 별도 |
| GitHub 스타 | ⭐ 70,184 | 36k+ | 25k+ | 별도 카운트 |
| 카테고리 | 기술 | 역할 |
|---|---|---|
| 언어 | Python 3.12+ | 타입 힌트 전면 활용 |
| 에이전트 프레임워크 | LangGraph + LangChain | 워크플로우 그래프 기반 에이전트 실행 |
| API 서버 | FastAPI + Uvicorn | Gateway API (포트 8001) |
| LLM 통합 | OpenAI, Anthropic, Google, DeepSeek 등 | YAML 설정으로 교체 가능 |
| MCP 클라이언트 | langchain-mcp-adapters | stdio/SSE/HTTP + OAuth 지원 |
| 패키지 관리 | uv | 빠른 Python 패키지 관리 |
| 코드 품질 | ruff | 린트 + 포맷팅 통합 |
| 문서 변환 | markitdown | PDF/PPT/Excel/Word → 마크다운 |
| 카테고리 | 기술 | 역할 |
|---|---|---|
| 프레임워크 | Next.js 16.2.6+ + React 19 | SSR + Turbo 개발 서버 |
| 언어 | TypeScript | 엄격 타입 체크 |
| UI 컴포넌트 | Radix UI | 접근성 기반 헤드리스 컴포넌트 |
| 스타일링 | Tailwind CSS | 유틸리티 퍼스트 |
| 코드 에디터 | CodeMirror 6 | JS/Python/HTML/CSS/JSON/MD 지원 |
| AI SDK | Vercel AI SDK + LangGraph SDK | 스트리밍 에이전트 통신 |
| 시각화 | XYFlow | 노드 기반 그래프 렌더링 |
| 마크다운 | Remark + Rehype + KaTeX + Shiki | GFM + 수학 + 코드 하이라이팅 |
| 패키지 관리 | pnpm 10.26.2 | 효율적 의존성 관리 |
| 카테고리 | 기술 | 역할 |
|---|---|---|
| 리버스 프록시 | Nginx (포트 2026) | 통합 진입점, API 라우팅 |
| 컨테이너 | Docker + Docker Compose | 개발/프로덕션 배포 |
| 오케스트레이션 | Kubernetes (옵션) | 프로비저너 모드 샌드박스 |
| 빌드 시스템 | Makefile | 전체 서비스 관리 |
| 상태 저장 | SQLite / PostgreSQL | 체크포인트 (선택) |
# 허용: app → deerflow (단방향 의존)
from deerflow.config import get_app_config # OK
# 금지: deerflow → app (CI 테스트로 강제)
from app.gateway.routers import ... # test_harness_boundary.py 실패!코어 에이전트 로직을 독립 패키지로 배포 가능하게 만드는 패턴입니다. Django와 Django REST Framework의 관계처럼, 하네스는 어떤 앱에서든 재사용 가능합니다.
| 에이전트가 보는 경로 | 실제 물리 경로 |
|---|---|
| /mnt/user-data/workspace | backend/.deer-flow/threads/{id}/user-data/workspace |
| /mnt/user-data/uploads | backend/.deer-flow/threads/{id}/user-data/uploads |
| /mnt/user-data/outputs | backend/.deer-flow/threads/{id}/user-data/outputs |
| /mnt/skills | deer-flow/skills/ |
replace_virtual_path() / replace_virtual_paths_in_command() 함수가 양방향 변환을 처리합니다.
config.yaml의 클래스 경로 문자열을 런타임에 실제 객체로 변환하는 시스템입니다. 누락된 패키지는 자동으로 설치 힌트를 제공합니다.
# config.yaml
models:
- use: "langchain_openai:ChatOpenAI" # → 런타임에 동적 import
sandbox:
use: "deerflow.sandbox.local:LocalSandboxProvider"
# 누락 시: "uv add langchain-google-genai" 힌트 자동 제공AgentState를 확장하여 커스텀 ThreadState를 만들고, make_lead_agent() 팩토리 패턴으로 동적 에이전트를 생성하는 방법을 배울 수 있습니다. RunnableConfig를 통한 런타임 설정 주입, Command(goto=END)로 그래프 실행을 인터럽트하는 패턴도 포함됩니다.
라우터 모듈 분리 패턴(6개 라우트 모듈이 각각 독립적), SSE(Server-Sent Events) 스트리밍 응답, Pydantic 응답 모델을 활용한 Gateway Conformance 테스트를 배울 수 있습니다.
before_model / after_model 훅 패턴, 미들웨어 순서의 중요성(ClarificationMiddleware가 반드시 마지막이어야 하는 이유), 상태 변환 체인에서의 부작용 관리를 배울 수 있습니다.
추상 Sandbox 인터페이스 → Provider 패턴(Local, Docker, K8s), 가상 경로 시스템으로 에이전트와 호스트 파일시스템 분리, acquire → get → release 라이프사이클 관리를 배울 수 있습니다.
langchain-mcp-adapters의 MultiServerMCPClient 활용법, stdio/SSE/HTTP 3가지 트랜스포트 모드, OAuth 토큰 플로우 + 자동 갱신, mtime 기반 캐시 무효화를 배울 수 있습니다.
LLM으로 대화에서 팩트 자동 추출(category: preference/knowledge/context/behavior/goal), 디바운스 큐로 효율적 배치 처리, 원자적 파일 I/O, whitespace 정규화 기반 중복 제거를 배울 수 있습니다.
Config 버전 관리(config_version 필드), $VARIABLE_NAME 문법으로 환경변수 해석, mtime 기반 자동 리로드(프로세스 재시작 없이 설정 반영), 4단계 설정 우선순위를 배울 수 있습니다.
| 항목 | 최소 사양 | 권장 사양 |
|---|---|---|
| Python | 3.12+ | 3.12+ |
| Node.js | 22+ | 22+ |
| 패키지 매니저 | pnpm, uv | pnpm 10.26+, uv 최신 |
| Docker | Docker Engine | Docker Desktop 최신 |
| RAM | 8GB+ (로컬 개발) | 16GB+ (Docker 샌드박스 포함) |
| 디스크 | 5GB+ (의존성 + Docker 이미지) | 10GB+ |
| LLM API 키 | OpenAI 또는 호환 API 1개 | Claude/GPT-4/Gemini 중 1개 |
| 네트워크 | LLM API 접속 필수 | 안정적 인터넷 |
권장 LLM 모델 조건: 100k+ 토큰 컨텍스트 윈도우 / 추론(reasoning) 기능 지원 / 멀티모달 입력 지원 / 강력한 tool-use 능력
git clone https://github.com/bytedance/deer-flow.git
cp config.example.yaml config.yaml # API 키 설정
make check && make install && make devhttp://localhost:2026 접속 → 간단한 대화 테스트 → 메모리 시스템 동작 확인(이름을 알려주고 다음 대화에서 기억하는지 테스트)
skills/custom/my-skill/ 디렉토리를 생성하고 SKILL.md를 작성합니다(YAML frontmatter: name, description, allowed-tools). 에이전트에게 해당 도메인 질문을 해보고 스킬이 로딩되는지 확인합니다.
간단한 MCP 서버를 만들고 extensions_config.json에 등록합니다. 에이전트에게 MCP 도구를 사용하는 작업을 요청하고, GET /api/mcp/config로 MCP 설정을 확인합니다.
packages/harness/deerflow/agents/middlewares/에 새 미들웨어 파일을 생성합니다. 대화 로그를 외부 서비스(예: Supabase)에 저장하는 미들웨어를 구현하고, 미들웨어 체인에 적절한 위치에 삽입합니다. make test로 기존 테스트 통과를 확인합니다.
DeerFlowClient를 사용하는 Python 스크립트를 작성합니다. 여러 리서치 주제를 순차적으로 에이전트에게 보내고, 결과를 마크다운 파일로 자동 저장하며, stream() 메서드로 실시간 진행 상황을 출력합니다.
| 주차 | 주제 | 핵심 학습 내용 |
|---|---|---|
| 1주차 | LangGraph 기초 | 공식 튜토리얼 완주 / AgentState·StateGraph·ToolNode / thread_state.py 분석 |
| 2주차 | 에이전트 아키텍처 | lead_agent/agent.py 정독 / 미들웨어 체인 이해 / Harness/App 분리 원칙 |
| 3주차 | 샌드박스 & 도구 | Docker SDK 학습 / 가상 경로 시스템 / MCP 스펙 읽기 / langchain-mcp-adapters |
| 4주차 | 메모리 & 상태 관리 | 메모리 시스템 코드 분석 / LLM 기반 팩트 추출 / SQLite vs PostgreSQL 체크포인터 |
| 5주차 | 프론트엔드 & 통합 | Next.js 16 + React 19 새 기능 / Vercel AI SDK 스트리밍 / XYFlow 시각화 |
| 6주차 | 프로덕션 배포 | Docker Compose 멀티서비스 / Nginx 리버스 프록시 / Kubernetes 프로비저너 / IM 채널 봇 통합 |
| 키워드 | 설명 |
|---|---|
| Super Agent Harness | 에이전트·도구·메모리·샌드박스·스킬을 통합 관리하는 런타임. 단순 에이전트 라이브러리보다 상위 개념 |
| Lead Agent | DeerFlow의 메인 에이전트. 사용자 요청을 받아 직접 처리하거나 서브에이전트에게 위임 |
| Subagent | 리드 에이전트가 task() 도구로 생성하는 하위 에이전트. general-purpose와 bash 두 종류 내장 |
| Middleware Chain | 15개+ 미들웨어가 순서대로 실행되는 처리 파이프라인. before_model/after_model 훅으로 요청/응답 변환 |
| ThreadState | LangGraph의 AgentState를 확장한 스레드별 상태 스키마. sandbox, artifacts, todos 등 포함 |
| Sandbox Provider | 코드 실행 환경의 추상화. Local(직접 실행), Docker(격리), K8s(프로비저너) 세 가지 구현 |
| Virtual Path System | 에이전트가 보는 경로(/mnt/user-data/)와 실제 경로를 매핑하는 추상화 계층 |
| MCP | Model Context Protocol. LLM이 외부 서비스와 상호작용하기 위한 프로토콜. stdio/SSE/HTTP + OAuth |
| Skills | SKILL.md로 정의되는 에이전트 능력 모듈. 태스크 요구에 따라 프로그레시브 로딩 |
| deerflow-harness | 퍼블리셔블 Python 패키지. 에이전트 코어 로직을 담으며 앱 계층과 엄격히 분리 |
| Gateway API | FastAPI 기반 REST API. 모델·MCP·스킬·메모리·업로드·아티팩트 6개 영역 관리 |
| Reflection System | config.yaml의 문자열 경로를 런타임에 실제 클래스/변수로 변환하는 동적 로딩 시스템 |
| Memory Facts | LLM이 대화에서 추출한 개별 사실. id, content, category, confidence, createdAt, source 구조 |
| Debounce Queue | 메모리 업데이트를 30초 지연 후 배치 처리하는 큐. 스레드별 중복 제거 포함 |
| Config Versioning | config_version 필드로 설정 스키마 변경 추적. make config-upgrade로 자동 마이그레이션 |
| IM Channel | 7개 메시징 플랫폼 통합 (Telegram/Slack/Feishu/Discord/DingTalk/WeCom/WeChat). MessageBus 기반 pub/sub 아키텍처 |
| DeerFlowClient | HTTP 없이 인프로세스로 DeerFlow를 사용하는 임베디드 Python SDK |
| Gateway Conformance | 임베디드 클라이언트 응답이 Gateway API의 Pydantic 모델과 일치하는지 검증하는 테스트 |
| XYFlow | React 기반 노드/엣지 그래프 라이브러리. 에이전트 워크플로우 시각화에 사용 |