OpenMAIC — Multi-Agent Interactive Classroom

Skill by ara.so — Daily 2026 Skills collection.

OpenMAIC (Open Multi-Agent Interactive Classroom) is a Next.js 16 / React 19 / TypeScript platform that converts any topic or document into a full interactive lesson. A multi-agent pipeline (LangGraph 1.1) generates slides, quizzes, HTML simulations, and project-based learning activities delivered by AI teachers and AI classmates with voice (TTS) and whiteboard support.

---

Project Stack

Layer	Technology
Framework	Next.js 16 (App Router)
UI	React 19, Tailwind CSS 4
Agent orchestration	LangGraph 1.1
Language	TypeScript 5
Package manager	pnpm >= 10
Runtime	Node.js >= 20

---

Installation

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install

Environment Configuration

cp .env.example .env.local

Edit .env.local — at minimum one LLM provider key is required:

# LLM Providers (configure at least one)
OPENAI_API_KEY=$OPENAI_API_KEY
ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
GOOGLE_API_KEY=$GOOGLE_API_KEY

# Recommended default model (Gemini 3 Flash = best speed/quality balance)
DEFAULT_MODEL=google:gemini-3-flash-preview

# Optional: MinerU for advanced PDF/table/formula parsing
PDF_MINERU_BASE_URL=https://mineru.net
PDF_MINERU_API_KEY=$MINERU_API_KEY

# Optional: access code for hosted mode
ACCESS_CODE=$OPENMAIC_ACCESS_CODE

Provider Config via YAML (alternative to env vars)

Create server-providers.yml in the project root:

providers:
  openai:
    apiKey: $OPENAI_API_KEY
  anthropic:
    apiKey: $ANTHROPIC_API_KEY
  google:
    apiKey: $GOOGLE_API_KEY
  deepseek:
    apiKey: $DEEPSEEK_API_KEY
  # Any OpenAI-compatible endpoint
  custom:
    baseURL: https://your-proxy.example.com/v1
    apiKey: $CUSTOM_API_KEY

---

Running the App

# Development
pnpm dev
# → http://localhost:3000

# Production build
pnpm build && pnpm start

# Type checking
pnpm tsc --noEmit

# Linting
pnpm lint

---

Docker Deployment

cp .env.example .env.local
# Edit .env.local with your API keys

docker compose up --build
# → http://localhost:3000

---

Vercel Deployment

# Fork the repo, then import at https://vercel.com/new
# Set env vars in Vercel dashboard:
#   OPENAI_API_KEY or ANTHROPIC_API_KEY or GOOGLE_API_KEY
#   DEFAULT_MODEL (optional, e.g. google:gemini-3-flash-preview)

One-click deploy button is available in the README; it pre-fills env var descriptions automatically.

---

Lesson Generation Pipeline

OpenMAIC uses a two-stage pipeline:

Stage	Description
Outline	AI analyzes topic/document and produces a structured lesson outline
Scenes	Each outline item is expanded into a typed scene: slides, quiz, interactive, or pbl

Scene Types

Type	Description
slides	AI teacher lectures with TTS narration, spotlight, laser pointer
quiz	Single/multiple choice or short-answer with AI grading
interactive	HTML-based simulation (physics, flowcharts, etc.)
pbl	Project-Based Learning — choose a role, collaborate with agents

---

API Usage — Generating a Classroom

REST: Start Generation Job

// POST /api/generate
const response = await fetch('/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    topic: 'Quantum Entanglement',
    // Optional: attach document content
    document: markdownString,
    // Optional: model override
    model: 'google:gemini-3-flash-preview',
  }),
});

const { jobId } = await response.json();

REST: Poll Job Status

// GET /api/generate/status?jobId=<jobId>
const poll = async (jobId: string) => {
  while (true) {
    const res = await fetch(`/api/generate/status?jobId=${jobId}`);
    const data = await res.json();

    if (data.status === 'completed') {
      console.log('Classroom URL:', data.classroomUrl);
      break;
    }
    if (data.status === 'failed') {
      throw new Error(data.error);
    }
    // status === 'pending' | 'running'
    await new Promise(r => setTimeout(r, 3000));
  }
};

REST: Export Slides

// GET /api/export/pptx?classroomId=<id>
const exportPptx = async (classroomId: string) => {
  const res = await fetch(`/api/export/pptx?classroomId=${classroomId}`);
  const blob = await res.blob();
  const url = URL.createObjectURL(blob);
  // trigger download
  const a = document.createElement('a');
  a.href = url;
  a.download = 'lesson.pptx';
  a.click();
};

// GET /api/export/html?classroomId=<id>
const exportHtml = async (classroomId: string) => {
  const res = await fetch(`/api/export/html?classroomId=${classroomId}`);
  const html = await res.text();
  return html;
};

---

OpenClaw Integration

OpenMAIC ships a skill for OpenClaw, enabling classroom generation from Feishu, Slack, Discord, Telegram, etc.

Install the Skill

# Via ClawHub (recommended)
clawhub install openmaic

# Manual install
mkdir -p ~/.openclaw/skills
cp -R /path/to/OpenMAIC/skills/openmaic ~/.openclaw/skills/openmaic

Configure OpenClaw

Edit ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "openmaic": {
        "config": {
          // Hosted mode — get access code from https://open.maic.chat/
          "accessCode": "$OPENMAIC_ACCESS_CODE",

          // Self-hosted mode — local repo + server URL
          "repoDir": "/path/to/OpenMAIC",
          "url": "http://localhost:3000"
        }
      }
    }
  }
}

OpenClaw Skill Lifecycle

Phase	What Happens
Clone	Detect existing checkout or clone fresh
Startup	Choose pnpm dev, pnpm build && pnpm start, or Docker
Provider Keys	Guide user to edit .env.local
Generation	Submit async job, poll, return classroom link

---

Custom Scene Development Pattern

Scenes are typed React components. To add a new scene type:

// types/scene.ts
export type SceneType = 'slides' | 'quiz' |