Guia para iniciantes do DeepTutor: implantação prática de um assistente de aprendizagem personalizado nativo de agentes

Nível iniciante | ~20 minutos | Você vai dominar a arquitetura central do DeepTutor, dois modos de implantação (Setup Tour + Docker), o uso do workspace em cinco modos e a configuração básica do TutorBot

---

Apresentação do projeto

O DeepTutor é uma plataforma de agentes de IA voltada para a aprendizagem: sua proposta central é “fazer a IA realmente apoiar o estudo, e não apenas conversar”. Desenvolvido pelo Laboratório de Inteligência de Dados da Universidade de Hong Kong (HKUDS), alcançou 10k Star em apenas 39 dias após a abertura do código em janeiro de 2026, e hoje já está entre os projetos de tecnologia educacional com IA mais acompanhados no GitHub.

O que o diferencia é sua arquitetura nativa de agentes: não é simplesmente “encaixar” a IA em uma interface de chat; em vez disso, tudo é desenhado ao redor do objetivo de aprendizagem, com uma cadeia completa de ferramentas de agentes colaborativos. Você envia materiais de estudo e ele ajuda a planejar a trilha, gerar questionários, acompanhar pontos de memória fraca — e até transforma fórmulas matemáticas em animações. O TutorBot vai além: cada tutor é um agente de IA independente, com memória e personalidade próprias, que pode até lembrar ativamente para você revisar.

Se você está procurando um assistente de aprendizagem com IA implantável localmente, com funcionalidades completas e alta extensibilidade, o DeepTutor vale a pena testar.

---

Perfil do público-alvo

• Desenvolvedores com 1–3 anos de experiência, interessados em agentes de IA e aplicações com LLM
• Entusiastas de tecnologia educacional que querem implantar ferramentas locais de aprendizagem com IA personalizadas
• Pessoas que desejam construir tutores com IA persistente (RAG + memória)

Dependências principais e ambiente

• Python 3.11+ e Node.js 18+
• Chave de API do LLM (OpenAI / Anthropic / DeepSeek etc.)
• Chave de API de Embedding (para busca vetorial no RAG)
• Docker (opcional; usado na implantação com Docker)

Estrutura completa em árvore do projeto

DeepTutor/
├── deeptutor/              # backend principal
│   ├── capabilities/        # cinco capacidades (chat, deep_solve, deep_question etc.)
│   ├── tools/               # camada de ferramentas (rag, web_search, code_execution etc.)
│   ├── tutorbot/            # TutorBot com tutores persistentes
│   ├── api/                 # serviço FastAPI
│   └── runtime/             # registro e escalonamento de plugins
├── deeptutor_cli/           # entrada CLI (Typer)
├── web/                     # frontend Next.js 16
├── scripts/start_tour.py    # script de instalação guiada e interativa
└── docker-compose.yml       # implantação com Docker

---

Passo a passo

Passo 1: Clone o repositório e crie um ambiente Python

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

# Crie o ambiente virtual Python (recomendado: conda)
conda create -n deeptutor python=3.11 && conda activate deeptutor
# ou use venv
python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate                          # Windows

Passo 2: Setup Tour interativo (recomendado)

O DeepTutor oferece um script de orientação interativa que trata automaticamente a instalação de dependências, preenchimento de configurações e testes de conexão — você não precisa editar manualmente o arquivo .env:

python scripts/start_tour.py

O script vai pedir que você escolha qual modo deseja usar:

• Modo Web (recomendado) — instala todas as dependências do front e do back, inicia um servidor temporário e abre o navegador para guiar você na configuração de LLM, Embedding e Search; em cada etapa há um teste de conexão em tempo real. Ao finalizar, o DeepTutor reinicia automaticamente.
• Modo CLI — tudo é feito no terminal; ideal para ambientes de servidor sem interface gráfica.

Após concluir a configuração, acesse http://localhost:3782.

Passo 3: Alternativa — configurar manualmente variáveis de ambiente no .env

Se você quiser controlar as configurações manualmente, primeiro copie o arquivo de exemplo:

cp .env.example .env

Depois edite .env, preenchendo pelo menos os itens obrigatórios abaixo (usando Defapi como exemplo):

# Configuração do LLM — usando Defapi como exemplo, acesso pela metade do preço ao Claude/GPT
LLM_BINDING=anthropic
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=sk-defapi-xxxxx
LLM_HOST=https://api.defapi.com/v1

# Configuração de Embedding — para busca vetorial no 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: busca na web
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-xxxxx

A lista completa de LLM Provider suportados está na tabela abaixo:

Passo 4: Instale as dependências e inicie o serviço

Modo Web (separação front/back):

# Instale as dependências do backend
pip install -e ".[server]"

# Instale as dependências do frontend
cd web && npm install && cd ..

# Inicie o backend (terminal 1)
python -m deeptutor.api.run_server
# O serviço roda em http://localhost:8001

# Inicie o frontend (terminal 2)
cd web && npm run dev -- -p 3782
# O serviço roda em http://localhost:3782

Abra http://localhost:3782 para usar.

Implantação rápida com Docker (sem instalar Python/Node.js):

# Primeiro configure .env (veja Passo 3)
cp .env.example .env
# Edite .env e preencha as API Keys

# Baixe a imagem oficial e inicie
docker compose -f docker-compose.ghcr.yml up -d

# Ver logs
docker compose logs -f

Passo 5: Comece rapidamente com o workspace em cinco modos

O núcleo do DeepTutor é um workspace de chat unificado, que suporta alternar entre cinco modos — todos os modos compartilham o mesmo contexto de conversa:

Chat (modo padrão) — diálogo fluido, com combinações de ferramentas como busca RAG, busca na web, execução de código e raciocínio profundo:

Você é um universitário revisando álgebra linear. No modo Chat, ative a ferramenta rag.
O DeepTutor vai buscar, na sua base de conhecimento, trechos de materiais relacionados para responder às perguntas.

Deep Solve (resolução profunda) — pipeline de resolução de problemas com múltiplos agentes: planejar → investigar → resolver → verificar, com referências precisas de origem em cada etapa:

deeptutor run deep_solve "Prove que √2 é irracional" -t reason

Quiz Generation (modo de criação de perguntas) — gera questões de avaliação com base na base de conhecimento, com validação automática:

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

Deep Research (pesquisa profunda) — divide o tema em subtemas, agenda agentes de RAG, web e papers acadêmicos em paralelo e gera um relatório de pesquisa com citações completas:

deeptutor run deep_research "O mecanismo de Atenção em Transformers"

Math Animator (animação matemática) — transforma conceitos matemáticos em animações visualizáveis (requer instalar dependências do Manim):

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

Passo 6: Construa a sua primeira base de conhecimento RAG

A base de conhecimento é o coração do DeepTutor: envie PDFs, arquivos Markdown e textos para construir uma base vetorial indexável:

Crie uma base via CLI:

# Crie a base de conhecimento e envie documentos
deeptutor kb create textbook --doc ./data/physics_ch1.pdf --doc ./data/physics_ch2.pdf

# Adicione documentos a uma base existente
deeptutor kb add textbook --doc ./data/physics_ch3.pdf

# Pesquise na base de conhecimento
deeptutor kb search textbook "Condição de convergência do gradiente descendente"

# Defina como base padrão
deeptutor kb set-default textbook

Operando pela interface Web:

1. Vá para a página “Gerenciamento de conhecimento”
2. Clique em “Criar nova base de conhecimento” e nomeie (por exemplo, my-textbook)
3. Envie arquivos PDF ou Markdown
4. No Chat, habilite a ferramenta RAG e selecione essa base de conhecimento

Passo 7: Crie seu primeiro TutorBot

TutorBot é o recurso “matador” do DeepTutor: cada Bot é um tutor de IA persistente e em múltiplas instâncias, com memória, personalidade e habilidades próprias:

# Crie um tutor de matemática (estilo de perguntas socráticas)
deeptutor bot create math-tutor \
  --name "Tutor de Matemática" \
  --persona "Professor de matemática socrático que usa perguntas de sondagem"

# Crie um coach de escrita
deeptutor bot create writing-coach \
  --name "Coach de Escrita" \
  --persona "Mentor paciente e orientado a detalhes para escrita"

# Veja todos os Bots
deeptutor bot list

# Inicie / pare o Bot
deeptutor bot start math-tutor
deeptutor bot stop math-tutor

TutorBot suporta integração por múltiplos canais (Telegram, Discord, Feishu, e-mail etc.), podendo iniciar ativamente lembretes de estudo e tarefas de revisão quando você não estiver por perto.

Passo 8: Visão geral dos comandos de uso diário via CLI

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

# Execução única
deeptutor run chat "Explique a transformação de Fourier" -t rag --kb textbook -l zh

# Gerencie sessões
deeptutor session list
deeptutor session open <session-id>

# Ver / limpar memória
deeptutor memory show summary
deeptutor memory show profile
deeptutor memory clear summary --force

# Ver configuração atual
deeptutor config show

# Liste todos os plugins e ferramentas
deeptutor plugin list

---

Solução de problemas comuns

1. Falha na conexão com LLM (401 Unauthorized ou 403 Forbidden)

# Verifique se a API Key está correta
cat .env | grep LLM_API_KEY

# Verifique a conectividade de rede (exemplo com Defapi)
curl -s https://api.defapi.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" | head -c 200

Causas comuns: API Key digitada incorretamente, variáveis de ambiente não foram aplicadas (reinicie o serviço) ou a rede não consegue acessar APIs no exterior.

2. A busca por Embedding não retorna resultados

# Verifique a configuração de Embedding
deeptutor config show | grep EMBEDDING

# Confirme que a base de conhecimento foi indexada com sucesso
deeptutor kb info textbook

Possíveis causas: a indexação ainda não terminou após o upload do documento, dimensão vetorial configurada incorretamente (precisa ser compatível com o modelo de Embedding), ou a consulta não se relaciona com o conteúdo do documento.

3. Porta em uso

# Encontre o processo usando a porta
lsof -i :8001  # porta do back-end
lsof -i :3782  # porta do front-end

# ou no Windows
netstat -ano | findstr :8001

Solução: finalize o processo em uso ou altere BACKEND_PORT e FRONTEND_PORT no .env.

4. Falha no health check do container Docker

# Veja logs detalhados do container
docker compose logs --tail=100

# Verifique se o arquivo .env existe e contém API Key válida
cat .env

5. O front-end não consegue conectar ao WebSocket do back-end

Ao fazer deploy remoto, garanta que o endereço externo correto esteja configurado:

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

Em seguida, reinicie o serviço para aplicar a configuração.

6. TutorBot não responde mensagens

Verifique o status do Bot e confirme que ele foi iniciado:

deeptutor bot list
deeptutor bot start <bot-id>

Bots em múltiplos canais (como Telegram) também exigem checar se a configuração do webhook na respectiva plataforma está correta.

---

Leitura complementar / Direções avançadas

Personalização do template do TutorBot Soul: ao editar o arquivo Soul do Bot, você pode definir a personalidade, o tom e a filosofia de ensino do assistente, criando um mentor de IA totalmente personalizado. Consulte os templates embutidos em deeptutor/tutorbot/souls/.

Desenvolvimento de plugins: o DeepTutor usa uma arquitetura de plugins em duas camadas (camada Tools + camada Capabilities). Você pode expandir qualquer funcionalidade escrevendo manifest.yaml + uma subclasse de BaseCapability. Para o guia detalhado de desenvolvimento, veja AGENTS.md.

Integração por múltiplos canais: o TutorBot suporta integração com Telegram, Discord, Feishu, WeCom corporativo e e-mail, etc.; assim, você pode conectar tutores de IA a qualquer plataforma que você use com frequência.

Motor nanobot: a camada inferior do TutorBot é movida por nanobot, um motor de agente de IA ultraleve — vale a pena aprofundar o estudo da implementação do Agent Loop.

Integração com LightRAG (no Roadmap): o próximo motor de base de conhecimento, LightRAG, será integrado; então as capacidades de busca de conhecimento serão significativamente aprimoradas.