DeerFlow 2.0 완전 정복 — ByteDance의 오픈소스 SuperAgent 런타임

2026년 2월, ByteDance가 DeerFlow 2.0을 공개했습니다. 출시 24시간 만에 GitHub Trending 1위를 차지했고, 한 달 만에 40,000 스타를 돌파했습니다.

DeerFlow는 단순한 멀티 에이전트 "프레임워크"가 아닙니다. 샌드박스, 메모리, 스킬, 도구, 서브 에이전트를 모두 갖춘 SuperAgent 런타임입니다. CrewAI나 AutoGen이 조립 키트라면, DeerFlow는 완성된 워크스테이션입니다.

이 시리즈에서는 DeerFlow 2.0의 설치부터 프로덕션 배포까지 전 과정을 다룹니다.

1. DeerFlow란?

DeerFlow (Deep Exploration and Efficient Research Flow)는 ByteDance가 개발한 오픈소스 SuperAgent 하니스입니다.

핵심 특징:

• MIT 라이선스 — 상업적 사용 가능
• LangGraph + LangChain 기반
• 9개 전문 에이전트 노드 (Supervisor, Researcher, Coder, Reporter 등)
• Docker/Kubernetes 샌드박스 — 격리된 코드 실행
• 영구 메모리 — 세션 간 학습과 개인화
• 스킬 시스템 — 모듈형 워크플로우 정의
• MCP 통합 — 외부 도구 서버 연결
• 메시지 게이트웨이 — Slack, Telegram, Feishu 연동

다른 프레임워크와 비교

핵심 차이: DeerFlow는 에이전트에게 실제 컴퓨터 환경(파일시스템, 샌드박스, 메모리, 도구)을 제공합니다. 다른 프레임워크는 이 인프라를 직접 구축해야 합니다.

2. 아키텍처 개요

DeerFlow 2.0은 2계층 아키텍처로 구성됩니다.

2-1. Harness (핵심 엔진)

deerflow-harness 패키지로 배포 가능한 핵심 런타임입니다.

• 에이전트 오케스트레이션 — LangGraph StateGraph로 에이전트 흐름 관리
• 도구 시스템 — 5가지 소스에서 도구를 로드
• 샌드박스 — Local/Docker/Kubernetes 3가지 모드
• 메모리 — JSON 기반 영구 저장소
• 스킬 — 마크다운 기반 워크플로우 정의
• MCP — 외부 도구 서버 연결

2-2. App (애플리케이션 계층)

실제 서비스를 구성하는 계층입니다.

2-3. Multi-Agent 워크플로우

LangGraph StateGraph 기반 9개 노드:

User Task → Supervisor → Planner → [Researcher, Coder, Analyst] → Reporter → Output
                                          ↑
                                    Human Feedback

3. 환경 설정

3-1. 시스템 요구사항

• Python: 3.12+
• Node.js: 22+
• RAM: 최소 4GB, 권장 8GB
• 디스크: 2GB 이상
• 패키지 매니저: uv (Python), pnpm (Frontend)

3-2. 설치

# 1. uv 설치 (Python 패키지 매니저)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 저장소 클론
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 3. Python 의존성 설치 (자동으로 venv 생성)
uv sync

# 4. 설정 파일 생성
cp conf.yaml.example conf.yaml

3-3. API 키 설정

conf.yaml 파일을 편집합니다:

models:
  - name: default
    display_name: Claude Sonnet
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-5-20250929
    api_key: $ANTHROPIC_API_KEY
    max_tokens: 4096
    temperature: 0.7

지원하는 모델 제공자:

• OpenAI — GPT-4, GPT-4o
• Anthropic — Claude Sonnet, Claude Opus
• DeepSeek — DeepSeek V3
• Ollama — 로컬 모델 (제한적 지원)

검색 도구도 설정합니다:

search:
  provider: tavily  # tavily, brave, duckduckgo 중 선택
  api_key: $TAVILY_API_KEY

3-4. 프론트엔드 설치

cd frontend
pnpm install
cd ..

3-5. 서비스 실행

터미널 3개가 필요합니다:

# 터미널 1: LangGraph Server (포트 2024)
cd backend && make dev

# 터미널 2: Gateway API (포트 8001)
cd backend && make gateway

# 터미널 3: Frontend (포트 3000)
cd frontend && pnpm dev

브라우저에서 http://localhost:3000 접속하면 DeerFlow UI가 나타납니다.

4. 첫 번째 태스크 실행

4-1. 웹 UI에서 실행

1. http://localhost:3000 접속
2. 채팅 입력창에 태스크를 입력합니다:

2026년 3월 기준 AI 에이전트 프레임워크 시장 동향을 조사하고,
주요 프레임워크 5개를 비교 분석하는 보고서를 작성해 주세요.

1. Supervisor가 태스크를 분석하고 계획을 세웁니다
2. Researcher가 웹 검색으로 정보를 수집합니다
3. Analyst가 데이터를 정리합니다
4. Reporter가 최종 보고서를 생성합니다

4-2. API로 실행

import requests

response = requests.post(
    "http://localhost:8001/api/v1/tasks",
    json={
        "message": "Compare DeerFlow vs CrewAI vs AutoGen for enterprise use cases",
        "model": "default",
    }
)

task_id = response.json()["task_id"]
print(f"Task started: {task_id}")

태스크 상태를 확인합니다:

status = requests.get(f"http://localhost:8001/api/v1/tasks/{task_id}")
print(status.json()["status"])  # "running", "completed", "failed"

4-3. CLI로 실행

cd backend
python -m deerflow.cli "Summarize the latest developments in multi-agent AI systems"

5. 도구 시스템 이해하기

DeerFlow는 5가지 소스에서 도구를 로드합니다:

5-1. 설정 기반 도구

conf.yaml에서 정의:

• Tavily Search — 웹 검색
• Brave Search — 대안 검색 엔진
• DuckDuckGo — 무료 검색
• Arxiv — 학술 논문 검색

5-2. MCP 도구

Model Context Protocol 서버에서 제공하는 도구:

mcp:
  servers:
    - name: filesystem
      command: npx
      args: ["-y", "@anthropic/mcp-filesystem-server", "/path/to/allowed"]
    - name: github
      command: npx
      args: ["-y", "@anthropic/mcp-github-server"]
      env:
        GITHUB_TOKEN: $GITHUB_TOKEN

5-3. 내장 도구

• present_files — 사용자에게 파일 제시
• ask_clarification — 사용자에게 질문
• view_image — 이미지 표시

5-4. 샌드박스 도구

격리된 환경에서 실행:

• bash — 셸 명령 실행
• ls, read_file, write_file — 파일 시스템 조작
• str_replace — 파일 내용 수정

5-5. Task 도구

서브 에이전트에 태스크 위임:

Supervisor → Task("Research the latest papers on DeerFlow") → Sub-agent

6. 실전 예제: 기술 리서치 보고서

DeerFlow에게 실제 리서치 태스크를 맡겨보겠습니다.

입력: "2026년 1분기 LLM 파인튜닝 기술 동향을 조사하고,
      QLoRA, DoRA, LoRA+ 기법을 비교하는 기술 보고서를 작성해 주세요.
      각 기법의 장단점, 적용 사례, 벤치마크 결과를 포함해 주세요."

DeerFlow의 처리 과정:

1. Supervisor: 태스크를 3개 서브태스크로 분해

- 각 기법별 최신 논문 조사

- 벤치마크 데이터 수집

- 비교 표 작성

1. Planner: 서브태스크를 Researcher와 Analyst에 할당
2. Researcher (병렬 실행):

- QLoRA 관련 최신 논문 3편 조사

- DoRA 관련 최신 논문 3편 조사

- LoRA+ 관련 최신 논문 3편 조사

1. Analyst: 수집된 데이터를 표로 정리
2. Reporter: 최종 보고서 생성 (마크다운 + 인용)

결과: 인용이 포함된 5-10페이지 분량의 기술 보고서가 생성됩니다.

7. 실전 데모: 한국어 AI 뉴스 리서치

A100 80GB GPU 서버에서 DeerFlow를 실제로 실행한 결과입니다.

태스크: "2026년 3월 AI 뉴스 Top 3를 검색하고 한국어 요약 작성"

============================================================
  DeerFlow 2.0 — AI News Research Agent Demo
  Model: Claude Sonnet 4.5 | Task: Korean AI News Brief
============================================================

  🔧 Tool: web_search({"query": "AI news March 2026"})
  🔧 Tool: web_search({"query": "artificial intelligence news this week March 24 2026"})
  🔧 Tool: web_search({"query": "latest AI technology news March 2026"})
  🔧 Tool: web_fetch({"url": "https://theaitrack.com/ai-news-march-2026-in-depth-and-concise/"})
  🔧 Tool: web_fetch({"url": "https://techcrunch.com/2026/03/13/the-biggest-ai-stories-..."})
  🔧 Tool: web_fetch({"url": "https://www.aiapps.com/blog/ai-news-march-2026-..."})

============================================================
  ✅ Research Complete!
  ⏱  Time: 45.3s
  🔧 Tool calls: 6
  📝 Output: 1,411 chars (한국어)
============================================================

에이전트가 자동으로 리서치 전략을 수립하고, 3번의 검색 + 3번의 페이지 크롤링을 실행한 뒤, 구조화된 한국어 뉴스 보고서를 생성했습니다. 총 소요 시간 1분 미만.

8. 벤치마크: DeerFlow vs CrewAI vs AutoGen

동일한 LLM(Claude Sonnet 4.5)과 동일한 검색 도구(Tavily)를 사용하여 세 프레임워크에 같은 태스크를 실행했습니다.

태스크: "2026년 3월 AI 뉴스 Top 3를 검색하고 2문장 요약 + 소스 URL 작성"

핵심 발견:

• DeerFlow가 CrewAI보다 33%, AutoGen보다 48% 빨랐습니다
• DeerFlow의 [citation:Title](URL) 형식이 가장 깔끔한 인라인 인용을 생성
• DeerFlow의 Plan-Execute 패턴이 병렬 도구 호출을 가능하게 하여 검색+크롤링이 더 적은 라운드트립으로 완료
• 동일 LLM 사용 시 세 프레임워크 모두 비슷한 수준의 콘텐츠 품질

참고: NVIDIA A100 80GB 서버에서 측정. 실행 시간에 API 지연이 포함됩니다 (네트워크 종속, 연산 종속 아님). 단일 실행 결과로 실제 성능은 API 부하에 따라 달라질 수 있습니다.

정리

이 글에서 다룬 내용:

• DeerFlow 2.0 — 단순 프레임워크가 아닌 SuperAgent 런타임
• 2계층 아키텍처 — Harness (핵심 엔진) + App (서비스 계층)
• 9개 에이전트 노드 — Supervisor 중심의 Plan-Execute 패턴
• 5가지 도구 소스 — 설정, MCP, 내장, 샌드박스, Task
• 설치 및 실행 — 3개 서비스 (LangGraph + Gateway + Frontend)
• 실전 데모 — 한국어 AI 뉴스 리서치 45초 완료
• 벤치마크 — DeerFlow가 CrewAI보다 33%, AutoGen보다 48% 빠름

다음 글에서는 DeerFlow의 핵심인 Multi-Agent 워크플로우를 심층 분석합니다. LangGraph StateGraph의 구조, 에이전트 간 통신 방식, Human-in-the-Loop 패턴을 코드와 함께 살펴봅니다.

이 글은 DeerFlow 2.0 실전 시리즈의 Part 1입니다.

- Part 1: DeerFlow 2.0 소개 + 설치 + 첫 태스크 (이 글)

- Part 2: Multi-Agent 워크플로우 심화

- Part 3: 커스텀 스킬 + MCP + 샌드박스

- Part 4: 프로덕션 배포 + 메시지 게이트웨이

여기서 쓴 코드 전체와 연습문제 풀이는 LLM Agent Cookbook에 있습니다.