OpenMAIC
OpenMAIC Features and Quickstart: Build a Small Interactive Lesson
A practical, source-backed OpenMAIC walkthrough for materials, agents, artifacts, providers, and a safe first lesson.
What you will learn
- Run a bounded OpenMAIC lesson
- Separate provider, artifact, and persistence failures
- Create a reproducible review record
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- A small lesson session is the safest way to exercise OpenMAIC features.
- Providers and media services form a capability matrix, not one universal key.
- Persist source hashes, artifacts, and human review decisions.
Start with the smallest classroom
OpenMAIC's useful unit is a lesson session: a topic or document enters a workbench, agents plan an activity, and the session produces inspectable artifacts. Begin with one short source file and one learning objective. This keeps provider errors, parsing problems, and generated content easy to distinguish.
The repository's documented baseline is Node.js 20+ and pnpm 10+. After cloning, install dependencies and copy `.env.example` to `.env.local`; configure one server-side model provider before adding media or search integrations.
Exercise the core features
A first pass should test four capabilities separately: material ingestion, an AI teacher or classmate response, one visual artifact such as slides or a whiteboard, and persistence after a page refresh. Then test an export such as editable PowerPoint or interactive HTML with a representative document.
OpenMAIC lists cloud and local options including OpenAI-compatible endpoints, Anthropic, Google, DeepSeek, Lemonade, and FunASR. Treat each provider as a separate capability matrix: chat, image, speech, search, and storage may need different credentials and failure handling.
Quickstart and failure diagnosis
Use `pnpm install`, create `.env.local`, and start the command documented by the release you pinned. If the UI loads but a lesson fails, check the browser request, server log, provider key, model name, and material size in that order. If export fails while chat succeeds, inspect the artifact renderer and file permissions rather than rotating API keys.
For a repeatable lesson, record the commit, provider, prompt, source-file hash, generated artifact paths, and human review decision. Never place provider keys in client-side code or commit `.env.local`.
A learning-oriented acceptance test
Call the run successful only when a reader can reproduce it, explain which agent or tool produced each artifact, and identify what still needs human review. Generated lessons are drafts until a subject-matter reviewer checks factual accuracy, accessibility, and age or audience appropriateness.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Pin Node/pnpm and clone the release.
- 2
Configure one server-side provider and ingest one short document.
- 3
Test response, artifact, persistence, and export separately.
- 4
Archive evidence and review generated teaching content.
Copy-ready example
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
cp .env.example .env.local
# add one provider key, then run the checked-out release commandFrequently asked questions
Can I enable every provider at once?
Start with one provider and add media/search services only after the core lesson is reproducible.
What should I keep for a bug report?
Keep the commit, provider/model, source hash, request ID, server log, and generated artifact path while redacting secrets.
Sources
- OpenMAIC README (captured 2026-08-31)Source checked 2026-08-31
- OpenMAIC repositorySource checked 2026-08-31