DeepTutor for Beginners: Practical Deployment of an Agent-Native Personalized Learning Assistant

Beginner-friendly | About 20 minutes | You’ll learn DeepTutor’s core architecture, two deployment methods (Setup Tour + Docker), how to use the five modes workspace, and the basics of TutorBot configuration

---

Project Overview

DeepTutor is an AI Agent platform built for learning. Its core mission is: 「Make AI truly assist learning—not just chat.」 It was developed by the Data Intelligence Lab at The University of Hong Kong (HKUDS). After going open-source in January 2026, it reached 10k Stars within 39 days, and it has quickly become one of the most talked-about AI education/edtech projects on GitHub.

What makes it unique is its Agent-Native architecture: it’s not about stuffing AI into a chat interface. Instead, everything is designed around the learning goal—forming a complete, collaborative toolchain of Agents. You upload your materials, and it helps you plan your learning path, generate quizzes, track weak memory points, and even turn math formulas into animations. TutorBot goes one step further—each TA is an independent AI Agent with its own memory and personality, able to proactively remind you to review.

If you’re looking for an AI learning assistant that is locally deployable, feature-complete, and highly extensible, DeepTutor is definitely worth a try.

---

Target Audience

• Developers with 1–3 years of experience who are interested in AI Agents and LLM applications
• Edtech enthusiasts who want to locally deploy a personalized AI learning tool
• Users who want to build persistent AI teaching assistants (RAG + memory)

Core Dependencies & Environment

• Python 3.11+、Node.js 18+
• LLM API Key (OpenAI / Anthropic / DeepSeek, etc.)
• Embedding API Key (for RAG vector search)
• Docker (optional; used for Docker deployment)

Full Project Structure Tree

DeepTutor/
├── deeptutor/              # Core backend
│   ├── capabilities/        # Five capabilities (chat, deep_solve, deep_question, etc.)
│   ├── tools/              # Tool layer (rag, web_search, code_execution, etc.)
│   ├── tutorbot/           # Persistent TutorBot teaching assistants
│   ├── api/                 # FastAPI service
│   └── runtime/            # Plugin registration and dispatch
├── deeptutor_cli/         # CLI entry (Typer)
├── web/                   # Next.js 16 frontend
├── scripts/start_tour.py  # Interactive installer script
└── docker-compose.yml     # Docker deployment

---

Step-by-Step Instructions

Step 1: Clone the Repository and Create a Python Environment

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Create a Python virtual environment (recommended: conda)
conda create -n deeptutor python=3.11 && conda activate deeptutor
# Or use venv
python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate                          # Windows

Step 2: Setup Tour Interactive Installation (Recommended)

DeepTutor provides an interactive guided script that automatically handles dependency installation, config prompts, and connection testing. You don’t need to manually edit the .env file:

python scripts/start_tour.py

The script will ask which usage mode you want to choose:

• Web Mode (Recommended) — Install both backend and frontend dependencies, start a temporary server, and open a browser to guide you through configuring LLM, Embedding, and Search. Each step includes real-time connection tests. After configuration is complete, DeepTutor restarts automatically.
• CLI Mode — Do everything in the terminal. Ideal for server environments without a graphical interface.

After setup, visit http://localhost:3782.

Step 3: Alternative — Manually Configure Environment Variables in .env

If you want to control configuration manually, first copy the example file:

cp .env.example .env

Then edit .env. At minimum, fill in the required fields below (using Defapi as an example):

# LLM configuration — Example: Defapi (half-price access to Claude/GPT)
LLM_BINDING=anthropic
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=sk-defapi-xxxxx
LLM_HOST=https://api.defapi.com/v1

# Embedding configuration — Used for RAG vector search
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-defapi-xxxxx
EMBEDDING_HOST=https://api.defapi.com/v1
EMBEDDING_DIMENSION=3072

# Optional: Web search
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-xxxxx

For the full list of supported LLM providers, see the table below:

Step 4: Install Dependencies and Start the Service

Web Mode (frontend/backend separated):

# Install backend dependencies
pip install -e ".[server]"

# Install frontend dependencies
cd web && npm install && cd ..

# Start backend (terminal 1)
python -m deeptutor.api.run_server
# Service runs at http://localhost:8001

# Start frontend (terminal 2)
cd web && npm run dev -- -p 3782
# Service runs at http://localhost:3782

Open http://localhost:3782 to use it.

Deploy with Docker (no need to install Python/Node.js):

# First configure .env (refer to Step 3)
cp .env.example .env
# Edit .env and fill in your API Key

# Pull official images and start
docker compose -f docker-compose.ghcr.yml up -d

# View logs
docker compose logs -f

Step 5: Quick Start with the Five-Mode Workspace

The core of DeepTutor is a unified chat workspace with five modes of switching. All modes share the same conversation context:

Chat (default mode) — Smooth conversations, supports tool combinations like RAG retrieval, web search, code execution, deep reasoning, and more:

You’re a college student reviewing linear algebra. In Chat mode, enable the rag tool.
DeepTutor will retrieve relevant textbook sections from your knowledge base to answer your question.

Deep Solve — A multi-Agent problem-solving pipeline: plan → investigate → solve → verify, with precise source citations at every step:

deeptutor run deep_solve "Prove that √2 is irrational" -t reason

Quiz Generation (question-creation mode) — Generate assessment questions based on your knowledge base, with automatic validation:

deeptutor run deep_question "Thermodynamics" --kb physics --config num_questions=5

Deep Research — Break a topic into subtopics, dispatch RAG, web, and academic-paper Agents in parallel, and produce a research report with complete citations:

deeptutor run deep_research "The Attention Mechanism in Transformers"

Math Animator — Convert mathematical concepts into visual animations (requires installing Manim dependencies):

pip install -r requirements/math-animator.txt
deeptutor run math_animator "Visualize a Fourier series"

Step 6: Build Your First RAG Knowledge Base

A knowledge base is the heart of DeepTutor—upload PDFs, Markdown, and text files to build a searchable vector knowledge base:

Create a knowledge base via CLI:

# Create a knowledge base and upload documents
deeptutor kb create textbook --doc ./data/physics_ch1.pdf --doc ./data/physics_ch2.pdf

# Append documents to an existing knowledge base
deeptutor kb add textbook --doc ./data/physics_ch3.pdf

# Search within the knowledge base
deeptutor kb search textbook "convergence conditions for gradient descent"

# Set as the default knowledge base
deeptutor kb set-default textbook

Operate via the Web UI:

1. Go to the「Knowledge Management」page
2. Click「Create Knowledge Base」and name it (e.g., my-textbook)
3. Upload a PDF or Markdown file
4. In Chat, enable the RAG tool and select that knowledge base

Step 7: Create Your First TutorBot

TutorBot is a killer feature of DeepTutor—each bot is a persistent, multi-instance AI teaching assistant with independent memory, personality, and skills:

# Create a math tutor (Socratic questioning style)
deeptutor bot create math-tutor \
  --name "Math Tutor" \
  --persona "Socratic math teacher who uses probing questions"

# Create a writing coach
deeptutor bot create writing-coach \
  --name "Writing Coach" \
  --persona "Patient, detail-oriented writing mentor"

# List all bots
deeptutor bot list

# Start / stop a bot
deeptutor bot start math-tutor
deeptutor bot stop math-tutor

TutorBot supports multi-channel integrations (Telegram, Discord, Feishu, email, etc.). It can proactively send learning reminders and review tasks when you’re away.

Step 8: CLI Daily Command Reference

# Interactive REPL (terminal chat)
deeptutor chat --capability deep_solve --kb textbook --tool rag

# One-shot execution
deeptutor run chat "Explain the Fourier transform" -t rag --kb textbook -l zh

# Manage sessions
deeptutor session list
deeptutor session open <session-id>

# View / clear memory
deeptutor memory show summary
deeptutor memory show profile
deeptutor memory clear summary --force

# View current configuration
deeptutor config show

# List all plugins and tools
deeptutor plugin list

---

Common Troubleshooting

1. LLM Connection Failed (401 Unauthorized or 403 Forbidden)

# Check whether the API Key is correct
cat .env | grep LLM_API_KEY

# Check network connectivity (example: Defapi)
curl -s https://api.defapi.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" | head -c 200

Common causes: incorrect API Key, environment variables not taking effect (restart the service), or the network can’t access overseas APIs.

2. Embedding Retrieval Returns No Results

# Check Embedding configuration
deeptutor config show | grep EMBEDDING

# Confirm the knowledge base has been indexed successfully
deeptutor kb info textbook

Possible causes: indexing hasn’t finished after uploading documents, the vector dimension is set incorrectly (must match the Embedding model), or the query doesn’t match the document content.

3. Port Is Already in Use

# Find processes using the port
lsof -i :8001  # backend port
lsof -i :3782  # frontend port

# Or on Windows
netstat -ano | findstr :8001

Fix: stop the process using the port, or modify BACKEND_PORT and FRONTEND_PORT in .env.

4. Docker Container Health Check Fails

# View detailed container logs
docker compose logs --tail=100

# Check that .env exists and contains valid API keys
cat .env

5. Frontend Can’t Connect to Backend WebSocket

For remote deployment, make sure you set the correct external address:

NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

Then restart the service so the configuration takes effect.

6. TutorBot Doesn’t Respond to Messages

Check the bot status and make sure it’s started:

deeptutor bot list
deeptutor bot start <bot-id>

Multi-channel bots (e.g., Telegram) also need you to verify that the corresponding platform’s webhook configuration is correct.

---

Further Reading / Advanced Directions

TutorBot Soul Template Customization: By editing the bot’s Soul files, you can define the teaching assistant’s personality, tone, and teaching philosophy to build a fully personalized AI mentor. Refer to the built-in templates under the deeptutor/tutorbot/souls/ directory.

Plugin Development: DeepTutor uses a two-layer plugin architecture (Tools layer + Capabilities layer). You can extend any functionality by writing manifest.yaml + a BaseCapability subclass. For detailed development guidance, see AGENTS.md.

Multi-channel Integration: TutorBot supports integrations such as Telegram, Discord, Feishu, Enterprise WeChat, and email. Connect your AI teaching assistant to any platform you commonly use.

nanobot Engine: TutorBot’s underlying system is driven by nanobot, an ultra-lightweight AI Agent engine. It’s worth digging into its Agent Loop implementation.

LightRAG Integration (Roadmap): The next-generation knowledge base engine, LightRAG, is planned to be integrated, which will significantly improve knowledge retrieval capabilities.