Deer-Flow 2.0은 딥 리서치를 어떻게 나눠 실행할까: 도입 검증 가이드
Deer-Flow 2.0의 LangGraph 기반 계획, 검색, 코드 실행, 보고 흐름을 설명하고, 설치 전 API 비용, 샌드박스 권한, 출처 검증 기준을 정리합니다.
Deer-Flow 2.0은 복잡한 조사 요청을 계획, 검색, 코드 실행, 보고서 작성 역할로 나누고, 상태 그래프와 샌드박스로 연결하는 오픈소스 딥 리서치 프레임워크입니다. 긴 작업을 자동화할 수 있지만 결과 품질은 연결한 모델과 검색 출처에 달려 있고, 다중 호출 비용과 코드 실행 권한도 사용자가 통제해야 합니다. 도입 전에는 화려한 결과 형식보다 계획 수정 가능성, 출처 추적, 실행 격리와 실패 시 중단 조건을 작은 과제로 검증해야 합니다.
Deer-Flow는 단일 답변형 챗봇과 무엇이 다른가요?
이름부터 짚고 넘어갈게요. Deer-Flow는 Deep Exploration and Efficient Research Flow의 약자입니다.
일반 대화형 답변과 달리 Deer-Flow는 질문을 받으면 연구 계획을 만들고 역할별 작업으로 나눕니다. 차이는 특정 챗봇보다 무조건 우월하다는 뜻이 아니라, 긴 조사의 중간 상태와 도구 실행을 프레임워크가 명시적으로 관리한다는 데 있습니다.
시스템은 LangGraph 기반 상태 기계로 작업 단계와 전환을 표현합니다.
| 비교 항목 | 기존 ChatGPT / 단순 RAG | Deer-Flow (Agentic Deep Research) |
|---|---|---|
| 작업 방식 | 요청과 답변 중심 | 목표 분해, 역할 실행, 결과 종합 |
| 도구 활용 | 제품별 제공 범위 | 검색, 코드, MCP, 샌드박스 연결 |
| Human-in-the-loop | 제품별로 다름 | 계획 단계에서 방향 수정 흐름 제공 |
| 최종 결과물 | 주로 텍스트와 첨부 결과 | 보고서와 설정된 출력 형식 |
역할을 나눴다고 각 에이전트가 독립 전문가가 되는 것은 아닙니다. 같은 기반 모델과 잘못된 출처를 공유하면 여러 역할이 같은 오류를 반복할 수 있으므로, 분업 구조와 검증 독립성을 구분해야 합니다.
2.0 문서는 리서치 외에 샌드박스 코드 실행과 장기, 단기 기억을 포함한 에이전트 하네스 방향을 소개합니다. 지원 기능과 설정은 현재 저장소를 기준으로 확인하고, 메모리와 실행 권한을 기본적으로 안전하다고 가정하지 않습니다.
설치 예시는 어떤 전제를 생략하고 있나요?
아래 명령은 글 작성 시점 저장소의 설치 흐름을 요약한 스냅샷입니다. Python, Node.js, Docker 요구 버전, 검색 제공자와 모델 인증, 노출 포트는 현재 README와 설정 파일에서 다시 확인해야 합니다.
1
2
3
4
5
6
7
8
9
10
# 1. 레포지토리 클론
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
# 2. 초기 설정 파일 생성 (이거 진짜 편함!)
make config
# 3. .env 파일에 OpenAI (또는 DeepSeek 등) API 키와 검색 API 세팅 후
# 도커로 한 방에 띄우기 (강력 추천)
make docker-init && make docker-start
브라우저 UI의 기본 접속 주소는 설치 시점 설정과 현재 문서를 대조합니다. 위 명령에는 패키지, 이미지 버전 고정, API 키 보관, 검색 제공자 한도, 외부 포트와 샌드박스 마운트가 생략돼 있습니다. 회사 데이터나 결제 계정을 연결하기 전에 테스트 키와 공개 자료만으로 실행 경계를 확인해야 합니다.
하나의 조사 요청은 어떤 역할을 거치나요?
프로젝트가 소개하는 흐름은 다음과 같이 읽을 수 있습니다.
- Coordinator가 요청과 현재 상태를 받아 작업을 시작합니다.
- Planner가 검색, 분석, 작성으로 이어지는 연구 로드맵을 만듭니다.
- Researcher가 설정된 검색 도구에서 근거 후보를 모읍니다.
- Coder가 필요한 계산이나 데이터 처리를 샌드박스에서 실행합니다.
- Reporter가 근거와 실행 결과를 정해진 출력 형식으로 종합합니다.
역할 이름이 달라도 같은 모델을 사용하면 판단 오류가 독립적으로 검증되지 않을 수 있습니다. Researcher가 잘못된 출처를 골랐는데 Reporter가 같은 요약만 보고 확신을 더할 수도 있습니다. 각 단계가 원문 URL, 실행 코드와 결과를 다음 단계에 어떤 형태로 넘기는지 확인해야 합니다.
계획 단계의 사람 개입은 무엇을 바꿔야 하나요?
사람은 계획이 너무 넓거나 핵심 질문을 빠뜨렸을 때 검색 전에 범위를 줄일 수 있어야 합니다. 승인 화면이 있어도 무엇이 바뀌었는지 알 수 없다면 형식적 개입에 그칩니다. 수정 전후의 하위 질문, 사용할 도구, 예상 호출 예산과 완료 조건을 비교해 보여 주는지가 중요합니다.
계획 승인 뒤에도 새로운 출처나 코드 실행으로 범위가 커질 수 있습니다. 일정 호출 수나 시간 예산을 넘으면 다시 확인을 요청하고, 외부 메시지 전송, 파일 쓰기처럼 조사와 다른 행동은 별도 권한으로 분리해야 합니다. 중간 개입은 무제한 자율 실행을 안전하게 만드는 단일 장치가 아닙니다.
출처와 코드 결과는 어떻게 검증하나요?
최종 보고서의 주장마다 어떤 검색 문서와 코드 출력이 근거인지 추적합니다. 검색 결과 제목만 인용하거나 다른 문서의 수치를 합친 경우를 찾고, 게시 시점과 원출처를 확인합니다. 여러 에이전트가 같은 2차 자료를 반복 인용했다면 독립 근거 수를 부풀리지 않아야 합니다.
코드 실행은 재현 가능한 입력, 패키지 버전, 명령과 출력 파일을 남기고 보고서의 수치와 대조합니다. 샌드박스에서 실행됐다는 사실만으로 코드가 논리적으로 맞거나 데이터 사용 권리가 있다는 뜻은 아닙니다. 오류 뒤 부분 파일이 남았는지, 재시도에서 이전 결과를 새 계산처럼 사용하지 않는지도 확인합니다.
비용과 반복 루프는 어떻게 제한하나요?
긴 조사에서는 Planner, Researcher, Coder와 Reporter가 여러 번 모델을 호출하고 검색, 코드 도구도 별도 비용을 만들 수 있습니다. 작업별 입력, 출력 토큰, 검색 호출, 샌드박스 시간과 재시도 횟수를 나눠 기록합니다. 단순히 마지막 보고서 한 건의 가격만 보면 실패한 경로와 중복 조사의 비용을 놓칩니다.
검색 결과가 부족할 때 같은 표현으로 계속 재검색하거나 Coder가 같은 오류를 반복할 수 있습니다. 최대 반복 횟수, 새 근거가 추가되지 않을 때의 중단, 예산을 넘을 때 사용자에게 돌아오는 조건을 정합니다. 중단은 실패를 숨기는 것이 아니라 확인되지 않은 범위를 보고서에 명시하는 방식이어야 합니다.
작은 모델과 큰 모델을 비교할 때는 모델명만 보지 말고 같은 조사 계획의 완료율, 근거 정확도와 호출 비용을 봅니다. 모든 역할에 같은 고비용 모델을 쓰기보다 계획, 검증이 중요한 단계와 단순 형식 변환을 구분할 수 있지만, 역할별 모델 변경은 자체 평가가 필요합니다.
샌드박스와 기억은 어떤 경계를 가져야 하나요?
Coder가 실행하는 환경에는 조사에 필요한 파일만 마운트하고 운영 자격 증명과 호스트 소켓을 주지 않는 편이 기본입니다. CPU, 메모리, 디스크, 실행 시간과 네트워크 목적지를 제한하고, 시간 초과 뒤 자식 프로세스와 임시 파일이 정리되는지 시험합니다. 보고서 생성에 파일 쓰기가 필요해도 허용 디렉터리를 좁힐 수 있습니다.
장기, 단기 기억에는 확정된 사용자 요구와 출처가 있는 조사 결과를 구분해 저장해야 합니다. 한 번의 잘못된 요약이 다음 조사에서 사실처럼 재사용되지 않도록 생성 시점, 원문과 수정, 삭제 경로를 남깁니다. 계정 연결을 해제했을 때 기억과 검색 캐시의 파생 데이터가 어디에 남는지도 확인합니다.
어떤 과제로 도입 가치를 판단하나요?
답과 근거를 사람이 이미 알고 있는 중간 규모 조사부터 시작합니다. 단일 대화형 검색, Deer-Flow의 역할 분리 흐름을 같은 자료, 시간 예산에서 비교하고 근거 정확도, 누락, 총 호출 비용, 사람 수정 시간을 기록합니다. 보고서, 프레젠테이션, 오디오처럼 출력 종류를 늘리기 전에 핵심 사실성이 유지되는지 먼저 봅니다.
Deer-Flow 2.0의 가치는 검색과 실행을 상태 있는 워크플로우로 묶고 사람이 계획에 개입할 지점을 제공한다는 데 있습니다. 적합성은 “슈퍼 에이전트”라는 이름이 아니라, 제한된 예산과 권한 안에서 근거와 실행 결과를 재현 가능하게 남기고 실패할 때 멈출 수 있는지로 판단해야 합니다.
중단 뒤 같은 조사 상태를 재개할 수 있나요?
장기 조사는 검색 API 오류나 모델 한도, 코드 실행 실패로 중간에 끊길 수 있습니다. 재개 기능을 평가할 때는 화면에 이전 단계가 보이는지만 확인하지 않습니다. 승인한 계획, 이미 검증한 출처, 실패한 코드와 남은 예산이 같은 작업에 정확히 이어지는지 봅니다. 일부만 복원되면 같은 검색과 호출이 반복되어 비용과 근거 중복이 커집니다.
체크포인트에는 민감한 입력과 API 응답이 포함될 수 있으므로 저장 위치와 보존 기간도 확인해야 합니다. 다른 사용자가 같은 상태를 볼 수 없는지, 작업 삭제 시 검색 캐시와 생성 파일까지 정리되는지 시험합니다. 재현성을 위해 상태를 오래 보관하는 선택과 데이터 최소 보관 원칙 사이의 경계를 조직이 정해야 합니다.
복구 시험은 일부러 한 단계를 실패시키는 방식으로 할 수 있습니다. Coder 실행을 중단한 뒤 재개했을 때 Researcher 결과를 다시 수집하지 않는지, Reporter가 실패 전의 부분 출력을 확정 결과로 쓰지 않는지 확인합니다. 성공한 데모 한 번보다 이런 실패 주입이 상태형 워크플로우의 운영 가치를 더 잘 드러냅니다.
함께 읽으면 이해가 이어지는 글
- DeerFlow 딥 리서치, 사내에 바로 둘 수 있을까: 구조, 보안, 운영 검증 — DeerFlow의 LangGraph 기반 역할 분담과 검색, 코드, 보고서 파이프라인을 살피고, 샌드박스, API 키, 출처, 비용을 검증하는 도입 기준을 정리합니다.
- WeKnora가 표, 수식 PDF RAG에 맞을까: 파싱, Hybrid Retrieval 검증 — WeKnora의 layout, 표, 수식 parsing과 BM25, dense, graph 검색, agent, MCP 구조를 살펴보고 한국어 문서 정확도, 인용, 자원, 운영 조건을 검증합니다.
- PraisonAI: YAML과 파이썬 코드로 구축하는 자율형 멀티 AI 에이전트 오케스트레이션 — PraisonAI는 코드 몇 줄이나 간단한 YAML 설정만으로 자율형 멀티 AI 에이전트 시스템을 구축하고 배포할 수 있게 해주는 오픈소스 프레임워크입니다. 100개 이상의 LLM 지원, 메모리 관리, RAG, MCP 도구 연동을…