For Teachers and Admins
This article explains how to build an app in Vocareum Atlas: you add an app, describe what you want to the Atlas agent, and refine the app until it is ready to share. It covers creating, copying and importing apps, working with the agent, and renaming or editing an app afterward.
Prerequisites
Before you build an app, check the following:
GenAI and Atlas are turned on for your organization. Your Organization Admin can ask Vocareum Support to turn them on.
You have a personal GenAI allowance that includes an Atlas agent model. The Atlas agent spends this allowance each time it builds. Organization Admins also need an allowance; the admin role does not grant one. For setup steps, refer to Configuring GenAI Access for Atlas.
To build on an app that someone else owns, you are an Editor of that app or an Organization Admin. Viewers can open and run an app but cannot build on it. For more information, refer to Sharing an Atlas Application.
If Atlas does not appear in the main navigation, either Atlas is not turned on for your organization, or you do not have a suitable GenAI allowance and no one has shared an app with you. Contact your Organization Admin.
If you can open Atlas but do not have a suitable allowance, the Atlas page shows a yellow banner. Organization Admins see "You cannot create apps", and the New app button is unavailable. Editors of a shared app see "You cannot build with Atlas" and can copy the app, but cannot build on it.
Adding an Atlas app
You can add an app in three ways: create a new app, copy an app you already have access to, or import an app you built in another organization or course. All three start on the Atlas page. To open it, select Atlas in the main navigation (the globe icon). The Atlas page lists your apps under the heading My apps.
Creating a new app
To create a new app, complete the following steps:
On the Atlas page, select New app. The Create new app window opens.
In App name, enter a name of up to 64 characters. You can rename the app later.
Select Create app.
The app opens in the Atlas build view, where you describe the app to the Atlas agent. For more information, refer to the Working with the Atlas agent section of this article.
A new app is published as soon as you create it, so you do not need a separate publish step. The app is available to anyone you share it with.
Copying an app
You can copy an app that you created, or an app that someone shared with you as an Editor. Viewers cannot copy an app.
To copy an app, complete the following steps:
On the Atlas page, find the app, then open the ⋮ menu on its tile.
Select Copy. For an app shared with you, the option is Copy to my workspace.
When the message "Copied to your workspace as" followed by the new name displays, the copy appears on the Atlas page. The copy has the same name as the original. To tell them apart, rename the copy. For the steps, refer to the Renaming an existing app section of this article.
A copy includes the app's published files only. It does not include the original app's shares, App history, chat history with the Atlas agent, learner activity, or data the app has saved.
If the app shows a Draft badge, its Owner has unpublished it, and the copy is empty. To publish it again, the Owner opens the ⋮ menu on its tile and selects Publish.
Importing an existing app
If you built an Atlas app in another Vocareum organization or in a course, you can import a copy of it into your workspace (your Atlas page) in this organization. Nothing is removed from the original, and nobody else can open the copy until you share it.
To import an app, complete the following steps:
On the Atlas page, select the arrow next to New app, then select Import an existing app.
In App to import, select the app. The list shows apps you authored, and apps in other organizations that are shared with you to edit. Draft apps are marked "(draft)" and import as an empty app, so publish the original first. If you select an app you built inside a course, every published app you built in that course part is imported.
Optionally, in Name in this organization, enter a new name. Leave it blank to keep the app's original name.
Select Import app.
You can import an app without a GenAI allowance, but you cannot build on it until you have one.
Working with the Atlas agent
You build an app by chatting with the Atlas agent. You describe what you want, the agent writes and updates the app, and you check the result in the app preview.
Navigating the Atlas interface
The build view has the following areas:
Agent panel: Select Agent in the left navigation to open the chat with the Atlas agent. This is where you write prompts and read the agent's replies.
App preview: The app preview shows the running app. Select the Reload preview icon to refresh it, or turn on Auto-refresh to refresh it automatically as the agent works. If the preview stops responding, or after the agent changes the app's server code, select the Restart app server icon. To see an icon's name, hover over it.
Files and Terminal: These show the app's files and a command line. You do not need them to build an app, but they are available if you want to inspect the files.
App actions menu (⋮): The menu in the app header contains App history, Rename app, Repair app, and Delete app. It appears only for the app's Owner and Editors.
The first time you open the Agent panel, a "Setting up Agent Mode" message displays for a few seconds.
Prompting the agent
When the chat is empty, the agent asks you to describe the app: who uses it, what they do in it, and what it should keep track of. You can start with a single sentence or a detailed description.
To send a prompt, complete the following steps:
In the Agent panel, enter your prompt in the message box.
Select the Send Prompt icon, or press Enter.
Wait for the agent to finish, then check the app preview.
The following tips help you get better results:
Describe the learner's experience, such as the scenario, the learner's role, the tools or characters they interact with, and what counts as success.
Ask for one change at a time when you refine the app, such as "Add a timer to each round" or "Make the customer persona more skeptical."
Describe what you see when something is wrong, such as "The Submit button does nothing after the third question."
While the agent is working, you can select Stop or press Esc to stop it. If you send another message while the agent is working, the message waits in a queue. Select Steer to have the agent pick up the message at its next step without stopping, or select Cancel to remove it.
To choose which AI model the agent uses, select the current model's name next to the message box. The models listed depend on your GenAI allowance. To start a new conversation, select the Clear chat context and history (eraser) icon. This clears the conversation immediately, without asking you to confirm, but does not change the app.
Adding context documents
You can give the agent your own materials, such as learning objectives, course content, scenarios, or rubrics, so that it builds the app around them.
To add a document, complete the following steps:
In the Files tree, open voc, then data, then apps. Your app's folder is the numbered folder inside apps; it contains files such as
index.html. The agent works in this folder.Right-click the app's folder and select Upload, or drag the file from your computer onto the folder.
In the Agent panel, tell the agent to use the file, for example: "Use the learning objectives in objectives.pdf to plan the three rounds of the simulation."
Important: Files in the app's folder are part of the app. Anyone who can open the app, including learners and people using a public link, can download any file in that folder, including the app's own code. Do not upload materials that learners should not see, such as answer keys or grading notes.
Editing an app
After you create an app, you can keep building it, rename it, or make a copy to try changes without affecting the original.
Renaming an existing app
On the Atlas page, only the app's Owner can rename it. Owners and Editors can also rename it from inside the build view.
To rename an app, complete the following steps:
On the Atlas page, open the ⋮ menu on the app's tile.
Select Rename. The Rename app window opens.
In App name, enter the new name, then select Save.
To rename an app from the build view, open the ⋮ menu in the app header and select Rename app.
Making a copy
Changes to an app go live right away, so to try a larger change without affecting learners, make a copy and work on the copy. For the steps, refer to the Copying an app section of this article.
Editing an existing app
Owners, Editors, and Organization Admins can keep building an app at any time.
To edit an app, complete the following steps:
On the Atlas page, find the app. To list only the apps you can edit, select the Owned by me or Shared to edit filter. Organization Admins can also select Org apps to list every app in the organization.
Select Build on the app's tile. The app opens in the build view in a new browser tab.
In the Agent panel, describe the change you want.
Important: Changes go live as soon as the agent makes them. There is no separate draft copy. Learners, viewers, and people using a public link receive the changes the next time they open or reload the app.
To take an app offline, the app's Owner opens the ⋮ menu on its tile on the Atlas page, selects Unpublish, and then confirms. The app is removed from the Atlas App list in every course it is shared with, people it is shared with can no longer open it, and assignments that already use it no longer display the app. Its shares are kept, so publishing it again restores access.
To return to an earlier version of the app, open the ⋮ menu in the app header, select App history, and then restore the version you want. A version is saved each time the agent finishes responding to a prompt. Restoring changes the app's files only; data the app has saved, such as learner responses, is not rolled back. The restore is saved as a new version, so you can undo it the same way. After you restore a version, select Restart app in the App History window to load the restored files. App history is available only to the app's Owner and Editors.