TL;DR

DeepTutor는 채팅 기반 에이전트 루프를 중심으로 챗·퀴즈·리서치·북·코드 실행 등 학습 워크플로를 하나의 런타임에서 연속적으로 운영하도록 설계된 오픈소스 플랫폼이다. UnifiedContext와 StreamBus를 통해 세션 메시지, 메모리, 페르소나, 스킬을 통합하고 Think→Act→Call Tool→Observe→Respond 순환으로 도구 호출과 응답을 처리한다. KB는 LlamaIndex, LightRAG, PageIndex 등 여러 검색 엔진을 선택해 연결할 수 있으며 서브에이전트와 파트너 연동, NDJSON 기반 CLI 제어, 3계층 메모리 그래프를 통해 근거 추적과 재현성을 확보한다. 도커·PyPI·소스 설치를 모두 지원해 로컬 또는 컨테이너 환경에서 빠르게 배포할 수 있지만 고급 RAG·임베딩 기능은 별도 모델 제공자 설정과 외부 서비스 연결을 필요로 한다.

주요 기능

• 채팅과 심화 학습 기능을 통합된 런타임에서 실행할 수 있다. 사용자는 Chat, Quiz, Research, Visualize, Solve, Mastery Path 같은 서로 다른 모드를 같은 에이전트 루프에서 전환하며 컨텍스트를 유지할 수 있다. 이로 인해 학습 목표만 바꾸고 상태와 기억은 연속적으로 재사용할 수 있다.
• 다중 검색 엔진 기반의 지식베이스를 생성하고 연결할 수 있다. LlamaIndex, PageIndex, GraphRAG, LightRAG, LightRAG Server, Obsidian 링크 같은 여러 엔진 중 하나를 KB별로 선택해 색인·검색 전략을 분리할 수 있다. 각 KB는 버전화되어 다시 빌드해도 이전 인덱스를 보존한다.
• 서브에이전트 및 파트너를 실시간으로 연결하고 컨텍스트로 사용할 수 있다. Claude Code나 Codex 같은 외부 에이전트를 consult_subagent로 호출해 그 실행을 스트리밍 방식으로 Activity 패널에 통합하며 과거 대화를 임포트해 참조할 수 있다. 파트너는 별도의 소울, 메모리, 라이브러리를 가지면서도 동일한 에이전트 엔진에서 동작한다.
• 파일 기반의 3계층 메모리와 편집 가능한 메모리 그래프를 제공한다. L1 원시 이벤트, L2 표면화된 사실, L3 교차 합성을 계층적으로 유지하고 각 합성 결과는 출처 추적이 가능하다. 사용자는 메모리 문서를 직접 읽고 업데이트하거나 감사를 수행할 수 있다.

어떻게 동작하는가

DeepTutor는 단일 TurnRuntimeManager 기반 에이전트 루프를 중심으로 동작하며, 사용자의 메시지와 세션·메모리·페르소나·스킬 매니페스트를 UnifiedContext로 통합해 처리한다. 에이전트는 순환적 사고(Think) → 도구 선택(Act) → 도구 호출(Call Tool) → 결과 관찰(Observe) → 응답(Respond) 플로우를 따르며, 각 단계의 이벤트는 StreamBus를 통해 웹 UI나 외부 CLI/SDK로 스트리밍된다. 도구 호출은 RAG, 메모리 읽기/쓰기, 웹 페치, 코드 실행, MCP 같은 플러그인형 툴 레지스트리를 통해 이뤄지며, 이들 결과는 동일한 컨텍스트에 다시 결합되어 다음 논리 단계의 입력으로 사용된다.

해결 문제

분리된 툴·문서·메모리로 인해 학습 컨텍스트가 흩어지는 문제를 하나의 에이전트 네이티브 런타임에서 해결한다. 이 플랫폼은 지식베이스, 노트, 퀴즈, 페르소나, 파트너 에이전트를 동일한 컨텍스트 공간에서 재사용 가능하게 연결해 학습 흐름을 끊기지 않게 유지한다. 또한 다양한 RAG 엔진과 플러그인 툴을 허용해 근거 기반 응답과 외부 기능 호출을 체계적으로 통합한다.

지금 주목받는 이유

활발한 릴리스와 20k 이상 스타를 바탕으로 에듀테크·에이전트 커뮤니티에서 빠르게 채택되었으며 arXiv 논문과 문서 사이트(deeptutor.info)로 설계 근거와 사용 가이드를 공개해 주목을 받았다. 최근 릴리스들에서 LightRAG Server, PyMuPDF4LLM 등 실무적 기능들이 잇따라 추가되어 실사용 준비성이 높아졌다. 에코시스템 측면에서 EduHub와 ClawHub 같은 스킬 레지스트리를 기본 통합한 점이 확산을 촉진했다.

차별점

• 워크플로 단일화로 모드 전환 시 엔진을 바꾸지 않고 목표만 전환하도록 설계되어, 컨텍스트와 메모리가 모든 모드에서 연속적으로 유지된다.
• KB별로 서로 다른 검색 엔진(예: LlamaIndex, LightRAG, PageIndex, Obsidian 링크)을 선택할 수 있어 운영 환경과 색인 전략을 분리해 사용할 수 있다.
• 서브에이전트(consult_subagent)와 파트너 시스템을 통해 외부 에이전트의 실시간 실행과 과거 대화 임포트를 동일한 런타임에서 관리할 수 있어 복합 작업을 위임하고 결과를 통합하기 쉽다.

사용 사례

• 로컬 또는 컨테이너 환경에서 개인화된 튜터 플랫폼을 구축해 학습 자료, 퀴즈, 북과 연계된 상호작용형 학습 경험을 제공할 수 있다. 교재 PDF를 업로드하고 RAG 기반 근거 응답과 자동 생성 퀴즈를 결합해 학습 경로를 만들 수 있다. 메모리 그래프를 통해 학습 진전과 오답 원인을 추적할 수 있다.
• CLI 중심 워크플로에서 자동화된 에이전트를 도구로 연결해 연구·리포트·질문 생성을 파이프라인화할 수 있다. deeptutor run의 NDJSON 출력은 다른 에이전트나 스크립트가 DeepTutor를 도구로 호출해 상태를 재사용하는 자동화에 적합하다. 세션 ID를 재사용해 연속적 작업을 유지할 수 있다.
• 멀티유저 배포에서 관리자가 모델·KB·스킬을 중앙에서 배포하고 각 사용자에 대해 격리된 워크스페이스를 제공할 수 있다. 인증을 활성화하면 관리자와 사용자 권한을 분리해 대규모 교육 환경을 운영할 수 있다. 파트너 채널을 IM 플랫폼에 연결해 실시간 상담형 봇으로도 활용할 수 있다.

시작하기

가장 간단한 경로는 PyPI 패키지를 설치한 뒤 워크스페이스를 만들고 deeptutor init으로 설정한 다음 deeptutor start로 백엔드와 프론트엔드를 함께 실행하는 것이다. 개발자라면 소스 체크아웃 후 가상환경을 만든 뒤 python -m pip install -e . 및 web 디렉터리에서 npm ci를 실행해 로컬 개발 서버로 동작시킬 수 있다. Docker 이미지(ghcr.io/hkuds/deeptutor:latest)로도 단일 컨테이너 배포가 가능하며 볼륨에 설정과 데이터가 유지된다.

요구사항

• Python 3.11 이상을 런타임 요구사항으로 사용하며 로컬 풀스택 설치는 Node.js(권장 20+ 또는 22 LTS)와 npm이 필요하다.
• 컨테이너 배포는 Docker 또는 Podman에서 동작하며, 호스트와의 모델 연결시 host.docker.internal 또는 --add-host 플래그 같은 네트워크 설정이 필요하다.
• RAG·임베딩·이미지·비디오 생성 같은 부가 기능을 사용하려면 별도의 모델 제공자(예: Ollama, LM Studio, llama.cpp 등)와 그에 맞는 Base URL 및 API 키를 Settings → Models에서 구성해야 한다.

이미지 분석