Guía para principiantes de DeepTutor: despliegue práctico de un asistente de aprendizaje nativo de agentes

Nivel inicial | ~20 minutos | Aprenderás la arquitectura central de DeepTutor, dos formas de despliegue (Setup Tour + Docker), el uso de un espacio de trabajo en cinco modos y la configuración básica de TutorBot

---

Descripción del proyecto

DeepTutor es una plataforma de agentes de IA orientada al aprendizaje, y su enfoque principal es «hacer que la IA ayude de verdad al estudio, no que se limite a conversar». Fue desarrollada por el Laboratorio de Inteligencia de Datos de la Universidad de Hong Kong (HKUDS). Tras su publicación como código abierto en enero de 2026, consiguió 10k Stars en solo 39 días; hoy en día ya es uno de los proyectos de edtech con IA más destacados en GitHub.

Su singularidad está en su arquitectura nativa de agentes: no se trata de “encajar” la IA en una interfaz de chat, sino de diseñar toda una cadena de herramientas de agentes colaborativos alrededor del objetivo de aprender. Subes material didáctico y te ayuda a planificar rutas de estudio, generar cuestionarios, rastrear tus puntos débiles de memoria e incluso puede convertir fórmulas matemáticas en animaciones. TutorBot va aún más allá: cada asistente actúa como un agente de IA independiente, con su propia memoria y personalidad, capaz de recordarte activamente que repases.

Si buscas un asistente de aprendizaje con IA desplegable localmente, con funciones completas y alta extensibilidad, DeepTutor merece la pena.

---

Perfil de público objetivo

• Desarrolladores con 1 a 3 años de experiencia, interesados en agentes de IA y aplicaciones con LLM
• Entusiastas de la tecnología educativa que quieran desplegar localmente herramientas de aprendizaje personalizadas con IA
• Usuarios que desean construir ayudantes de IA persistentes (RAG + memoria)

Dependencias clave y entorno

• Python 3.11+、Node.js 18+
• Clave de API del LLM (OpenAI / Anthropic / DeepSeek, etc.)
• Clave de API de Embeddings (para búsquedas vectoriales en RAG)
• Docker (opcional; se usa en el despliegue con Docker)

Estructura completa del árbol del proyecto

DeepTutor/
├── deeptutor/              # Backend central
│   ├── capabilities/      # Cinco capacidades (chat, deep_solve, deep_question, etc.)
│   ├── tools/             # Capa de herramientas (rag, web_search, code_execution, etc.)
│   ├── tutorbot/          # TutorBot: ayudante persistente
│   ├── api/               # Servicio FastAPI
│   └── runtime/           # Registro y orquestación de plugins
├── deeptutor_cli/         # Entrada de CLI (Typer)
├── web/                   # Frontend en Next.js 16
├── scripts/start_tour.py  # Script interactivo de instalación guiada
└── docker-compose.yml     # Despliegue con Docker

---

Pasos, uno a uno

Paso 1: Clonar el repositorio y crear el entorno de Python

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

# Crear un entorno virtual de Python (recomendado: conda)
conda create -n deeptutor python=3.11 && conda activate deeptutor
# O usar venv
python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate                           # Windows

Paso 2: Setup Tour de instalación interactiva (recomendado)

DeepTutor incluye un script de guía interactiva que gestiona automáticamente la instalación de dependencias, el llenado de configuraciones y la prueba de conexión. No necesitas editar manualmente el archivo .env:

python scripts/start_tour.py

El script te pedirá que elijas qué modo usar:

• Modo Web (recomendado) — Instala dependencias del front y del back, inicia un servidor temporal y abre el navegador para guiarte a completar la configuración de LLM, Embedding y Search; en cada paso hay pruebas de conexión en tiempo real. Cuando terminas la configuración, DeepTutor se reinicia automáticamente.
• Modo CLI — Se hace todo en la terminal, ideal para entornos de servidor sin interfaz gráfica.

Cuando termines, accede a http://localhost:3782.

Paso 3: Alternativa — Configurar manualmente variables de entorno en .env

Si prefieres controlar la configuración tú mismo, primero copia el archivo de ejemplo:

cp .env.example .env

Luego edita .env. Al menos completa estos campos obligatorios (como ejemplo, con Defapi):

# Configuración del LLM — usando Defapi, acceso a mitad de precio con Claude/GPT
LLM_BINDING=anthropic
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=sk-defapi-xxxxx
LLM_HOST=https://api.defapi.com/v1

# Configuración de Embedding — para búsqueda vectorial en 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

# Opcional: búsqueda web
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-xxxxx

La lista completa de LLM Provider compatibles se muestra en la tabla:

Paso 4: Instalar dependencias y arrancar el servicio

Modo Web (front y back separados):

# Instalar dependencias del backend
pip install -e ".[server]"

# Instalar dependencias del frontend
cd web && npm install && cd ..

# Iniciar el backend (terminal 1)
python -m deeptutor.api.run_server
# El servicio corre en http://localhost:8001

# Iniciar el frontend (terminal 2)
cd web && npm run dev -- -p 3782
# El servicio corre en http://localhost:3782

Abre http://localhost:3782 para usarlo.

Despliegue con Docker en un solo comando (sin instalar Python/Node.js):

# Primero configura .env (referencia: Paso 3)
cp .env.example .env
# Edita .env e introduce las API Key

# Descargar la imagen oficial e iniciar
docker compose -f docker-compose.ghcr.yml up -d

# Ver logs
docker compose logs -f

Paso 5: Primeros pasos rápidos con el espacio de trabajo en cinco modos

El núcleo de DeepTutor es un espacio de trabajo de chat unificado con soporte para cambiar entre cinco modos; todos los modos comparten el mismo contexto de conversación:

Chat (modo predeterminado) — Conversaciones fluidas, con combinaciones de herramientas como RAG, búsqueda web, ejecución de código y razonamiento profundo:

Eres un estudiante universitario y estás repasando álgebra lineal. Al habilitar la herramienta rag en el modo Chat,
DeepTutor buscará en tu base de conocimientos el contenido de material relevante para responder a tu pregunta.

Deep Solve (resolución profunda) — Pipeline de resolución de problemas mediante múltiples agentes: planificación → investigación → resolución → validación. En cada paso hay referencias exactas de las fuentes:

deeptutor run deep_solve "Demuestra que √2 es un número irracional" -t reason

Quiz Generation (modo de evaluación) — Genera preguntas de evaluación a partir de la base de conocimientos y admite verificación automática:

deeptutor run deep_question "Termodinámica" --kb physics --config num_questions=5

Deep Research (investigación profunda) — Divide un tema en subtemas, programa agentes de RAG, web y artículos académicos en paralelo y genera un informe de investigación con citas completas:

deeptutor run deep_research "El mecanismo de Attention en Transformers"

Math Animator (animador matemático) — Convierte conceptos matemáticos en animaciones visuales (requiere instalar dependencias de Manim):

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

Paso 6: Construir tu primera base de conocimientos RAG

La base de conocimientos es el corazón de DeepTutor: sube PDFs, Markdown y archivos de texto para construir una base vectorial consultable:

Crear una base de conocimientos por CLI:

# Crear la base de conocimientos y subir documentos
deeptutor kb create textbook --doc ./data/physics_ch1.pdf --doc ./data/physics_ch2.pdf

# Añadir documentos a una base de conocimientos existente
deeptutor kb add textbook --doc ./data/physics_ch3.pdf

# Buscar en la base de conocimientos
deeptutor kb search textbook "Condiciones de convergencia del descenso por gradiente"

# Establecer como base de conocimientos predeterminada
deeptutor kb set-default textbook

Operar mediante la interfaz Web:

1. Ve a la página de «Gestión de conocimientos»
2. Haz clic en «Crear una nueva base de conocimientos» y asígnale un nombre (por ejemplo, my-textbook)
3. Sube archivos PDF o Markdown
4. En Chat, habilita la herramienta RAG y selecciona esa base de conocimientos

Paso 7: Crear tu primer TutorBot

TutorBot es la función estrella de DeepTutor: cada bot es un asistente de IA persistente y con múltiples instancias. Tiene memoria propia, personalidad y habilidades:

# Crear un asistente de matemáticas (estilo de preguntas tipo Sócrates)
deeptutor bot create math-tutor \
  --name "Asistente de matemáticas" \
  --persona "Profesor de matemáticas socrático que usa preguntas de sondeo"

# Crear un coach de escritura
deeptutor bot create writing-coach \
  --name "Coach de escritura" \
  --persona "Paciente y meticuloso mentor de escritura"

# Ver todos los Bots
deeptutor bot list

# Iniciar / detener un Bot
deeptutor bot start math-tutor
deeptutor bot stop math-tutor

TutorBot admite conexiones por múltiples canales (Telegram, Discord, Feishu, correo electrónico, etc.), y puede iniciar recordatorios de estudio y tareas de repaso por iniciativa propia cuando tú no estés.

Paso 8: Resumen de comandos para uso diario con CLI

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

# Ejecución única
deeptutor run chat "Explica la transformada de Fourier" -t rag --kb textbook -l zh

# Administrar sesiones
deeptutor session list
deeptutor session open <session-id>

# Ver / borrar memoria
deeptutor memory show summary
deeptutor memory show profile
deeptutor memory clear summary --force

# Ver la configuración actual
deeptutor config show

# Listar todos los plugins y herramientas
deeptutor plugin list

---

Solución de problemas frecuentes

1. Fallo de conexión al LLM (401 Unauthorized o 403 Forbidden)

# Verifica que la API Key sea correcta
cat .env | grep LLM_API_KEY

# Comprueba la conectividad de red (ejemplo con Defapi)
curl -s https://api.defapi.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" | head -c 200

Causas comunes: API Key mal escrita, variables de entorno sin efecto (reinicia el servicio) o que la red no pueda acceder a APIs en el extranjero.

2. No hay resultados en la búsqueda de Embeddings

# Verifica la configuración de Embedding
deeptutor config show | grep EMBEDDING

# Confirma que la base de conocimientos ya se indexó
deeptutor kb info textbook

Posibles causas: aún no se ha completado el indexado después de subir documentos, dimensión del vector configurada de forma incorrecta (debe coincidir con el modelo de Embedding) o que la consulta no coincide con el contenido de los documentos.

3. El puerto está ocupado

# Buscar el proceso que usa el puerto
lsof -i :8001  # puerto del backend
lsof -i :3782  # puerto del frontend

# O en Windows
netstat -ano | findstr :8001

Solución: finaliza el proceso que está usando el puerto o modifica BACKEND_PORT y FRONTEND_PORT en .env.

4. Falló la comprobación de salud del contenedor Docker

# Ver logs detallados de los contenedores
docker compose logs --tail=100

# Verifica que el archivo .env exista y contenga API Key válida
cat .env

5. El frontend no puede conectar al WebSocket del backend

En despliegues remotos, asegúrate de que la dirección externa sea la correcta:

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

Luego reinicia el servicio para que la configuración surta efecto.

6. TutorBot no responde a los mensajes

Revisa el estado del Bot y confirma que esté iniciado:

deeptutor bot list
deeptutor bot start <bot-id>

Los Bots en varios canales (como Telegram) también requieren comprobar que la configuración del webhook del canal sea correcta.

---

Lecturas adicionales / Direcciones de nivel avanzado

Personalización de plantillas de TutorBot Soul: editando el archivo Soul del Bot puedes definir la personalidad, el tono y la filosofía docente del asistente, creando un tutor de IA totalmente personalizado. Consulta las plantillas integradas en el directorio deeptutor/tutorbot/souls/.

Desarrollo de plugins: DeepTutor usa una arquitectura de plugins en dos capas (capa de Tools + capa de Capabilities). Puedes ampliar cualquier funcionalidad escribiendo manifest.yaml + una subclase de BaseCapability. La guía detallada de desarrollo está en AGENTS.md.

Integración con múltiples canales: TutorBot admite canales como Telegram, Discord, Feishu, WeCom (correo) y email; podrás conectar tu tutor de IA con cualquier plataforma que uses habitualmente.

Motor nanobot: la base del TutorBot está impulsada por nanobot, un motor de agentes de IA ultraligero. Vale la pena estudiar en profundidad la implementación del Agent Loop.

Integración de LightRAG (Roadmap): el motor de próxima generación de base de conocimientos LightRAG se integrará próximamente, y para entonces las capacidades de búsqueda de conocimientos mejorarán de forma significativa.