DeerFlow 2.0: 서브 에이전트, 기억, 샌드박스를 하나의 런타임에 담은 ByteDance의 오픈소스 '슈퍼 에이전트 하네스'

DeerFlow는 Deep Exploration and Efficient Research Flow의 약자로, 처음에는 ByteDance가 공개한 오픈소스 딥 리서치 프레임워크였다. README는 이후의 변화를 설명한다. 커뮤니티가 데이터 파이프라인, 슬라이드 생성, 대시보드, 콘텐츠 자동화에까지 쓰기 시작했는데 이는 팀이 예상하지 못한 용도였다. 그래서 DeerFlow가 단순한 조사 도구가 아니라 에이전트가 실제로 일을 해내는 기반을 제공하는 하네스, 곧 런타임이라는 점을 깨닫고 처음부터 다시 만들었다. 2.0은 1.x와 코드를 공유하지 않으며, 기존 딥 리서치 프레임워크는 1.x 브랜치에 남고 활발한 개발은 2.0으로 옮겨갔다. README는 2.0 출시 후 2026년 2월 28일 DeerFlow가 GitHub Trending 1위에 올랐다고도 적었다. 2026년 10월 13일 기준 저장소는 별 약 83,766개, 포크 11,654개, MIT 라이선스, Python 코드이고 2025년 5월 7일에 만들어졌으며 마지막 푸시는 10월 13일이다.

README의 정의에 따르면 DeerFlow 2.0은 더 이상 직접 엮어야 하는 프레임워크가 아니라 바로 쓸 수 있고 완전히 확장 가능한 슈퍼 에이전트 하네스다. LangGraph와 LangChain 위에 만들어졌고 파일 시스템, 기억, 스킬, 샌드박스를 인식하는 실행, 복잡한 다단계 작업을 위해 계획하고 서브 에이전트를 만들어 내는 능력을 갖췄다. 모델에 구애받지 않아 OpenAI 호환 API를 구현한 LLM이면 쓸 수 있지만, 긴 컨텍스트(10만 토큰 이상), 추론, 멀티모달 입력, 강한 도구 사용을 갖춘 모델에서 가장 잘 동작한다고 하며, README는 Doubao-Seed-2.0-Code, DeepSeek v3.2, Kimi 2.5로 실행하기를 강하게 권한다. 검색과 크롤링에는 ByteDance의 BytePlus가 자체 개발한 InfoQuest 도구 모음을 통합했고 무료 온라인 체험도 있다.

핵심 기능은 몇 묶음으로 나뉜다. 스킬과 도구. 워크스페이스 사이드바의 'Capability Center'에서 플러그인(MCP 서버와 Lark/Feishu 연동)과 스킬을 관리하고, 내장 스킬과 사용자가 만들거나 가져온 스킬은 따로 나열되며, Community 탭에서는 .skill 아카이브를 가져올 수 있다. 서브 에이전트. 각 서브 에이전트는 기본적으로 독립된 컨텍스트에서 돌아 메인이나 다른 서브 에이전트의 내용을 볼 수 없으므로 눈앞의 작업에 집중한다. task 호출은 isolated(기본)와 snapshot 모드를 받는데, snapshot은 부모가 유지한 대화와 압축 요약을 기록으로 넘기며 입력 토큰이 더 든다. 컨텍스트 엔지니어링. 세션 안에서 완료된 하위 작업을 요약하고 중간 결과를 파일 시스템으로 내리며 더는 필요 없는 내용을 압축하여, 긴 다단계 작업에서도 창이 넘치지 않게 한다. 도구 출력에도 미리보기 예산과 구조화된 요약이 있다. 장기 기억은 DeerMem이라는 구성요소가 맡아 대화, 사용자, 에이전트별로 디바운스하며 기본 정숙 시간은 30초, 최대 대기는 300초다. 이밖에 세션 목표, 수동 컨텍스트 압축, 채팅 아카이브, 문서 선반이 있는 프로젝트, 예약 작업(cron 실행 시각 미리보기, 수명 주기와 안전 상한 포함), 내장 Python 클라이언트, 터미널 워크벤치가 있다.

실행 방법에 대한 README 설명은 세밀하다. 빠른 시작에서는 먼저 모델을 설정하고 Docker(권장) 또는 로컬 개발을 고르며, 디버깅에는 LangGraph Studio를 선택적으로 쓴다. 기존 체크아웃 업그레이드, 여러 제공자, 기존 실행에 대한 스트림 작업, 개인 액세스 토큰에도 전용 절이 있다. 샌드박스 절은 특히 읽을 만하다. AIO 샌드박스는 불확실한 암묵적 셸 결과나 세션 생성 뒤에 회수되며, 회수 전에 게이트웨이는 컨테이너 ID나 Pod UID를 격리 디렉터리에 기록한다. 이 기록은 정지 실패나 게이트웨이 재시작 후에도 남는다. 오래된 기록은 백엔드가 남은 컨테이너나 Pod가 없다고 확인한 뒤에야 지우며, 삭제 확인 응답이나 헬스 체크 실패만으로는 충분하지 않다. 실패 경로를 이렇게 보수적으로 다루는 것은 장시간 무인 운용을 염두에 두고 쓰였음을 보여 준다.

가장 먼저 읽어야 할 것은 보안 장이다. README는 DeerFlow가 시스템 명령 실행, 리소스 조작, 비즈니스 로직 호출 같은 높은 권한의 능력을 가지며 기본적으로 로컬 신뢰 환경, 곧 127.0.0.1 루프백으로만 접근되는 환경에 배포하도록 설계됐다고 말한다. LAN이나 퍼블릭 클라우드 서버처럼 여러 단말이 접근할 수 있는 환경에 엄격한 조치 없이 두면 무단 호출, 인터넷 스캐너에 발견되어 위험한 작업이 대량으로 실행되는 사태, 컴플라이언스와 법적 위험이 생긴다. Docker 스택은 진입 포트를 127.0.0.1에만 공개하고 로컬 make dev와 make start도 루프백에만 바인딩한다. 다른 기기에서 접근하려면 .env에 BIND_HOST를 설정하되 먼저 조치를 마쳐야 한다. iptables나 하드웨어 방화벽으로 IP 허용 목록을 만들고, nginx 같은 리버스 프록시로 강한 사전 인증을 켜며, 에이전트와 신뢰 기기를 전용 VLAN에 둔다. 새 인스턴스에는 계정이 없으므로 루프백 전용이 아닌 배포는 시작 직후 /setup으로 관리자 계정을 만들어야 한다. README는 또 게이트웨이 관리자가 stdio MCP 서버를 등록할 수 있고 이것이 게이트웨이 컨테이너 안에서 명령을 실행한다고 밝힌다. API는 허용 목록(기본 npx와 uvx)으로 제한하고 임의 코드를 평가할 수 있는 인자를 거부하지만 이는 다층 방어일 뿐 경계가 아니므로, 게이트웨이 관리자는 호스트의 코드 실행 권한과 같은 것으로 취급해야 한다.

우리의 판단은 DeerFlow 2.0에서 배울 것이 별 수가 아니라 공학적 선택이라는 것이다. 서브 에이전트 격리, 컨텍스트 요약, 파일 시스템으로 내리기, 샌드박스 회수처럼 보통 내부에 숨은 세부 사항이 문서화되어 있어 에이전트 인프라를 직접 만드는 사람에게 드문 참고 자료다. 유의점은 세 가지다. README가 매우 길고 변화가 빨라 많은 절이 현재 소스의 동작을 설명하므로 배포 전에 자신의 버전과 대조해야 한다. 힘과 위험이 같은 데서, 곧 명령 실행과 파일 읽기·쓰기에서 나오므로 기본 루프백 바인딩을 가볍게 바꾸지 말아야 한다. 모델 추천에는 특정 업체로 기운 경향이 보이며, 실제 결과는 연결한 모델과 작업에 달려 있다. 먼저 테스트 데이터만 든 디렉터리로 격리된 컨테이너에서 실행해 본 뒤, 실제 데이터와 외부 채널을 연결할지 결정하길 권한다.