DeepTutor : démarrage — déploiement pratique d’un assistant d’apprentissage « Agent-Native »

Niveau débutant | ~20 minutes | Vous maîtriserez l’architecture centrale de DeepTutor, ses deux modes de déploiement (Setup Tour + Docker), l’utilisation d’un espace de travail en cinq modes, ainsi que la configuration de base de TutorBot

---

Présentation du projet

DeepTutor est une plateforme d’agents IA dédiée à l’apprentissage ; son objectif central est « permettre à l’IA d’assister réellement l’apprentissage, et pas seulement de discuter ». Développée par le Laboratoire d’Intelligence des Données de l’Université de Hong Kong (HKUDS), elle a décroché 10k Stars en 39 jours après son open source en janvier 2026, et fait déjà partie des projets d’IA éducative les plus suivis sur GitHub.

Sa particularité tient à son architecture Agent-Native : ce n’est pas simplement une IA « insérée » dans une interface de chat. Le système est conçu autour de l’objectif d’apprentissage et s’accompagne d’une chaîne complète d’outils d’agents collaboratifs. Vous importez un manuel : DeepTutor vous aide à planifier votre parcours, à générer des quiz, à repérer vos lacunes de mémoire, et peut même transformer des formules mathématiques en animations. TutorBot va encore plus loin : chaque assistant est un agent IA autonome, doté de sa propre mémoire et de sa personnalité, capable de vous rappeler de réviser de lui-même.

Si vous cherchez un assistant d’apprentissage IA déployable localement, avec des fonctionnalités complètes et une excellente extensibilité, DeepTutor mérite d’être essayé.

---

Profil des lecteurs cibles

• Développeurs avec 1 à 3 ans d’expérience, intéressés par les AI Agents et les applications LLM
• Passionnés d’EdTech qui veulent déployer localement un outil d’apprentissage IA personnalisé
• Utilisateurs souhaitant construire un tuteur IA persistant (RAG + mémoire)

Dépendances clés et environnement

• Python 3.11+ et Node.js 18+
• Clé d’API LLM (OpenAI / Anthropic / DeepSeek, etc.)
• Clé d’API d’Embedding (pour la recherche vectorielle RAG)
• Docker (optionnel, utilisé en cas de déploiement Docker)

Arborescence complète du projet

DeepTutor/
├── deeptutor/              # backend principal
│   ├── capabilities/      # cinq capacités (chat, deep_solve, deep_question, etc.)
│   ├── tools/             # couche d’outils (rag, web_search, code_execution, etc.)
│   ├── tutorbot/         # TutorBot — tuteur persistant
│   ├── api/               # service FastAPI
│   └── runtime/           # enregistrement et dispatch des plugins
├── deeptutor_cli/         # point d’entrée CLI (Typer)
├── web/                   # frontend Next.js 16
├── scripts/start_tour.py  # script d’installation guidé interactif
└── docker-compose.yml     # déploiement Docker

---

Étapes pas à pas

Étape 1 : cloner le dépôt et créer un environnement Python

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

# Créer un environnement virtuel Python (recommandé : conda)
conda create -n deeptutor python=3.11 && conda activate deeptutor
# ou utiliser venv
python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate                            # Windows

Étape 2 : Setup Tour — installation interactive (recommandé)

DeepTutor propose un script d’installation guidé et interactif : il gère automatiquement l’installation des dépendances, la saisie des paramètres et les tests de connexion. Vous n’avez pas besoin d’éditer manuellement le fichier .env :

python scripts/start_tour.py

Le script vous demandera de choisir le mode d’utilisation :

• Mode Web (recommandé) — installe toutes les dépendances front et back, démarre un serveur temporaire et ouvre le navigateur pour vous guider dans la configuration de LLM, Embedding et Search. Chaque étape inclut des tests de connexion en temps réel. Une fois la configuration terminée, DeepTutor redémarre automatiquement.
• Mode CLI — tout se fait dans le terminal, adapté aux environnements serveurs sans interface graphique.

Une fois la configuration terminée, rendez-vous à l’adresse http://localhost:3782.

Étape 3 : optionnel — configurer manuellement les variables d’environnement .env

Si vous souhaitez contrôler la configuration manuellement, commencez par copier le fichier exemple :

cp .env.example .env

Puis éditez .env en remplissant au minimum les champs obligatoires suivants (exemple avec Defapi) :

# Configuration LLM — exemple avec Defapi : accès à moitié prix à Claude/GPT
LLM_BINDING=anthropic
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=sk-defapi-xxxxx
LLM_HOST=https://api.defapi.com/v1

# Configuration Embedding — pour la recherche vectorielle RAG
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

# Optionnel : recherche web
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-xxxxx

La liste complète des fournisseurs LLM supportés se trouve dans le tableau ci-dessous :

Étape 4 : installer les dépendances et démarrer le service

Mode Web (front et back séparés) :

# Installer les dépendances backend
pip install -e ".[server]"

# Installer les dépendances frontend
cd web && npm install && cd ..

# Démarrer le backend (terminal 1)
python -m deeptutor.api.run_server
# Le service tourne sur http://localhost:8001

# Démarrer le frontend (terminal 2)
cd web && npm run dev -- -p 3782
# Le service tourne sur http://localhost:3782

Ouvrez http://localhost:3782 pour l’utiliser.

Déploiement Docker en une commande (sans installer Python/Node.js) :

# D’abord configurer .env (voir l’étape 3)
cp .env.example .env
# Éditer .env et renseigner la clé API

# Récupérer les images officielles et lancer
docker compose -f docker-compose.ghcr.yml up -d

# Voir les logs
docker compose logs -f

Étape 5 : prise en main rapide de l’espace de travail en cinq modes

Le cœur de DeepTutor est un espace de travail de discussion unifié, avec prise en charge de la bascule entre cinq modes. Tous les modes partagent le même contexte de conversation :

Chat (mode par défaut) — dialogue fluide, avec combinaisons d’outils incluant la recherche RAG, la recherche web, l’exécution de code et le raisonnement approfondi :

Vous êtes étudiant(e) à l’université et vous révisez l’algèbre linéaire. En activant l’outil rag en mode Chat,
DeepTutor récupère depuis votre base de connaissances le contenu de manuel correspondant pour répondre à la question.

Deep Solve (résolution approfondie) — pipeline de résolution de problèmes multi-agents : planifier → enquêter → résoudre → valider ; chaque étape inclut des références sources précises :

deeptutor run deep_solve "Prouver que √2 est irrationnel" -t reason

Quiz Generation (mode quiz) — génère des questions d’évaluation à partir de la base de connaissances, avec validation automatique :

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

Deep Research (recherche approfondie) — décompose un thème en sous-sujets, orchestre en parallèle des agents RAG, web et articles académiques, puis génère un rapport de recherche avec citations complètes :

deeptutor run deep_research "Le mécanisme d’Attention dans les Transformers"

Math Animator (animation mathématique) — transforme les concepts mathématiques en animations visualisées (nécessite l’installation des dépendances Manim) :

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

Étape 6 : construire votre première base de connaissances RAG

La base de connaissances est le cœur de DeepTutor : importez des PDF, Markdown et fichiers texte pour construire une base vectorielle consultable.

Créer une base via CLI :

# Créer une base de connaissances et y uploader des documents
deeptutor kb create textbook --doc ./data/physics_ch1.pdf --doc ./data/physics_ch2.pdf

# Ajouter des documents à une base existante
deeptutor kb add textbook --doc ./data/physics_ch3.pdf

# Rechercher dans la base
deeptutor kb search textbook "Conditions de convergence de la descente de gradient"

# Définir la base par défaut
deeptutor kb set-default textbook

Opérer via l’interface Web :

1. Allez dans la page « Gestion des connaissances »
2. Cliquez sur « Nouvelle base », donnez un nom (ex. my-textbook)
3. Uploadez des fichiers PDF ou Markdown
4. Dans Chat, activez l’outil RAG et choisissez cette base de connaissances

Étape 7 : créer votre premier TutorBot

TutorBot est la fonctionnalité « killer » de DeepTutor : chaque bot est un tuteur IA persistant, multi-instances, avec mémoire, personnalité et compétences indépendantes.

# Créer un tuteur de maths (style questions à la Socrate)
deeptutor bot create math-tutor \
  --name "Maths Tutor" \
  --persona "Socratic math teacher who uses probing questions"

# Créer un coach d’écriture
deeptutor bot create writing-coach \
  --name "Writing Coach" \
  --persona "Patient, detail-oriented writing mentor"

# Voir tous les Bots
deeptutor bot list

# Démarrer / arrêter un Bot
deeptutor bot start math-tutor
deeptutor bot stop math-tutor

TutorBot prend en charge plusieurs canaux d’accès (Telegram, Discord, Feishu, e-mail, etc.) et peut lancer de lui-même des rappels d’apprentissage et des tâches de révision lorsque vous n’êtes pas là.

Étape 8 : commandes pour un usage quotidien en CLI (aperçu)

# REPL interactif (chat dans le terminal)
deeptutor chat --capability deep_solve --kb textbook --tool rag

# Exécution en une fois
deeptutor run chat "Expliquer la transformation de Fourier" -t rag --kb textbook -l zh

# Gérer des sessions
deeptutor session list
deeptutor session open <session-id>

# Voir / effacer la mémoire
deeptutor memory show summary
deeptutor memory show profile
deeptutor memory clear summary --force

# Voir la configuration actuelle
deeptutor config show

# Lister tous les plugins et outils
deeptutor plugin list

---

Résolution des problèmes fréquents

1. Échec de connexion à la LLM (401 Unauthorized ou 403 Forbidden)

# Vérifier si la clé API est correcte
cat .env | grep LLM_API_KEY

# Vérifier la connectivité réseau (exemple avec Defapi)
curl -s https://api.defapi.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" | head -c 200

Causes fréquentes : clé API mal saisie, variables d’environnement non prises en compte (redémarrer le service), ou réseau incapable d’accéder aux API à l’étranger.

2. Aucun résultat pour la recherche Embedding

# Vérifier la configuration Embedding
deeptutor config show | grep EMBEDDING

# Confirmer que la base de connaissances a bien été indexée
deeptutor kb info textbook

Causes possibles : l’index n’est pas terminé après l’upload du document, dimension vectorielle mal configurée (doit correspondre au modèle Embedding), ou la requête ne correspond pas au contenu des documents.

3. Le port est déjà utilisé

# Trouver le processus utilisant le port
lsof -i :8001  # port backend
lsof -i :3782  # port frontend

# ou sur Windows
netstat -ano | findstr :8001

Solution : arrêter le processus en cours d’exécution, ou modifier BACKEND_PORT et FRONTEND_PORT dans .env.

4. Échec de la health check des conteneurs Docker

# Voir les logs détaillés du conteneur
docker compose logs --tail=100

# Vérifier que le fichier .env existe et contient une clé API valide
cat .env

5. Le frontend ne parvient pas à se connecter au WebSocket du backend

En déploiement distant, assurez-vous que l’adresse externe correcte est configurée :

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

Puis redémarrez le service pour appliquer la configuration.

6. TutorBot ne répond pas aux messages

Vérifiez l’état du Bot et assurez-vous qu’il est démarré :

deeptutor bot list
deeptutor bot start <bot-id>

Pour des Bots multi-canaux (comme Telegram), il faut aussi vérifier si la configuration du webhook sur la plateforme correspondante est correcte.

---

Lecture complémentaire / pistes d’évolution

Personnaliser les templates TutorBot Soul : en éditant le fichier Soul du Bot, vous pouvez définir la personnalité de l’assistant, son ton et sa philosophie pédagogique, afin de créer un mentor IA totalement personnalisé. Reportez-vous aux templates intégrés dans le répertoire deeptutor/tutorbot/souls/.

Développement de plugins : DeepTutor utilise une architecture de plugins en deux couches (couche Tools + couche Capabilities). Vous pouvez étendre n’importe quelle fonctionnalité en écrivant manifest.yaml + une sous-classe de BaseCapability. Le guide de développement détaillé se trouve dans AGENTS.md.

Intégration multi-canaux : TutorBot prend en charge Telegram, Discord, Feishu, WeChat Work en entreprise, l’e-mail, etc. Vous pouvez connecter votre assistant IA à n’importe quelle plateforme que vous utilisez au quotidien.

Moteur nanobot : le niveau inférieur de TutorBot est propulsé par nanobot. C’est un moteur d’agents IA ultra-léger, qui mérite d’être étudié en profondeur pour comprendre son Agent Loop.

Intégration LightRAG (dans la roadmap) : le moteur de nouvelle génération de base de connaissances LightRAG sera bientôt intégré. À ce moment-là, les capacités de recherche de connaissances seront considérablement améliorées.