Vocational task engine
Enable experimental vocational lessons with procedural practice, decisions, and consequence feedback.
The vocational task engine generates lessons around a workplace task: what the learner needs to do, which tools are involved, when to continue or stop, and how to check completion. It combines briefing slides, interactive procedural practice, explanations, and task challenges.
This feature is experimental and disabled by default. Start with Getting started to configure OpenMAIC and an LLM provider, then enable the flags below on your deployment.
Suitable tasks
Choose a concrete task with an ordered workflow, tools or equipment, observable conditions, and a decision such as proceed, stop, recheck, or hand over. Equipment inspection, assembly preparation, and maintenance safety checks are examples.
The outline prompt asks for a task briefing first, followed by practice segments and challenges that serve the same job. The planner is instructed to assess suitability: a concept-only request should use ordinary slides and interactive widgets instead of forcing procedural practice. The generated outline still needs review.
Enable the feature
Add these entries to the OpenMAIC application's .env.local:
OPENMAIC_ENABLE_VOCATIONAL=true
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI=true| Flag | Purpose | When it takes effect |
|---|---|---|
OPENMAIC_ENABLE_VOCATIONAL | Allows the server to use vocational task planning and procedural content generation. | At runtime; restart the application after changing its process environment. |
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI | Shows the experimental vocational switch on the home page. | At build time; rebuild the production application after changing it. |
Both flags accept true or 1; unset values leave them disabled. Restart pnpm dev after editing local development configuration. For production, set the public flag before pnpm build, and provide the server flag when starting the application. These flags belong to the OpenMAIC application, not the documentation server. See Configuration.
Showing the switch does not enable the server path by itself. Vocational generation requires both the server flag and requirements.taskEngineMode from the generation request. When the server flag is off, the request follows the ordinary standard or interactive generation path.
Generate a vocational lesson
- Open the OpenMAIC home page and configure the model you want to use.
- Turn on the experimental switch labelled 职教任务 (vocational task).
- Describe the work task, learner level, tools, decision points, and completion criteria. Attach relevant course materials when available.
- Generate the outline, review it, then continue into the classroom.
Example request:
Create a vocational lesson on pre-work safety checks for electric-vehicle
battery maintenance, for learners with basic workshop knowledge. Begin with
a task briefing, then practise checking protective equipment and tools,
interpreting inspection results, deciding GO/STOP, and confirming handover.
Use the supplied materials for procedure details and approved limits.
Include feedback for incorrect decisions and a way to reset each exercise.An enabled vocational course records the server-effective mode and can show a Vocational Mode badge in the course list. Subsequent scene generation and retries carry the saved mode so procedural practice remains available while the server flag is enabled. A mode badge describes the generation mode, not a guarantee that every scene is a procedural widget.
What learners practise
The procedural-skill widget is generated as an HTML exercise inside the existing interactive scene renderer. Its prompt requests visible controls, a task and tool list, ordered steps, progress, feedback, completion conditions, and reset. At least one interaction should involve a choice, measurement, or judgment; an incorrect choice should show an operational consequence such as a blocked step or a required recheck.
Completion conditions are intended to follow the exercise's state. Reset should restore pending steps, progress, feedback, and controls. Because the HTML is generated by the model, inspect these behaviours before using a lesson. These exercises provide lightweight procedural practice; their local step state is not a durable platform assessment record or a physical simulation.
Troubleshooting
| Symptom | What to check |
|---|---|
| No vocational switch appears | Check NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI in the application build environment; rebuild production or restart development. |
| The switch is visible but ordinary content is generated | Check the server's OPENMAIC_ENABLE_VOCATIONAL value and that the switch was on when submitting the request. |
| A theory topic produces no procedural practice | The planner is instructed to avoid procedural widgets when the request has no workplace operation or meaningful decision. Describe a concrete task. |
| Controls, reset, or feedback do not behave correctly | Review the generated scene HTML and regenerate the affected content. Enabling the mode does not guarantee the model implements every interaction correctly. |
Implementation notes
The feature introduced by PR #685 uses the existing generation and interactive rendering pipeline. The relevant components on current main are:
| Component | Responsibility |
|---|---|
| Feature flags | resolveVocationalActive combines the request's taskEngineMode with the server flag; the UI flag is separate. |
| Outline route and task-engine prompt | Select the vocational planner and carry the effective mode in the stream's completion event. |
| Scene-content route and generation package | Re-check the server gate and pass task fields to the procedural content prompt. Disabled procedural outlines can be downgraded to diagrams by outline fallback; the widget generator also refuses ungated procedural content. |
| Preview mode helper and scene-generation hook | Persist the effective course mode and forward it for later scenes and retries, including the follow-up fix in PR #716. |
Procedural outlines carry procedureType (repair, assembly, inspection, operation, or custom), task, tools, steps, successCriteria, and errorConsequences. The content templates turn these fields into the generated exercise.
Teacher actions reuse the existing platform-to-iframe messages: SET_WIDGET_STATE, HIGHLIGHT_ELEMENT, ANNOTATE_ELEMENT, and REVEAL_ELEMENT. The procedural prompt asks for stable step selectors and a shared state update path for learner controls and SET_WIDGET_STATE, including completedSteps. This keeps procedural practice within the existing scene and action contracts.
This work is supported by the National Key Research and Development Program of China under Grant 2024YFC3308500.