# Building and publishing a coach

> Create a coach, set its persona, guidance style, content and session ending, test it, then publish it and share its link or embed code.

- Plans: All plans
- Canonical: https://docs.devlin.ai/coaches/build-a-coach

A coach is an AI helper that learners talk to around their practice: it gives real-time guidance while a linked simulation is running, debriefs the learner after one is complete, or answers questions on its own. Any member of a workspace can create, edit and publish coaches, on every plan.

A coach differs from a simulation in these ways. It plays a helper, not a character in a scenario. It has no evaluation, so it never produces a score or a pass or fail result of its own. And it can be linked to simulations and evaluators so that it knows what the learner did there.

## Before you start

- Coaches are created from the Coaches tab of **Studio**. See [Finding your way around the app](https://docs.devlin.ai/get-started/find-your-way-around).
- Generating a coach from a description uses credits. Starting from scratch does not. A coach's conversations with learners use credits like a simulation's. See [Credits, usage and low-credit alerts](https://docs.devlin.ai/plans-and-billing/credits-and-usage).
- Attaching documents and links as source materials while you create a coach needs one of these plans: Core, Team, Enterprise. See [Source materials](https://docs.devlin.ai/knowledge/source-materials).
- If the coach should guide or debrief a simulation, create that simulation first. See [Creating a simulation](https://docs.devlin.ai/simulations/create-a-simulation).

## Steps

1. On the Coaches tab of **Studio**, select **New coach**. A dialog asks you to **Explain what this coach should help with**.
2. Describe what the coach should do and, if it should work with simulations you already have, say which ones.
3. To add a library name or source materials first, use the full **Create New Coach** screen instead (see The Create New Coach screen below).
4. Select **Generate coach**. To skip generation, select **Start from scratch** instead: a blank draft named "Untitled Coach" opens in the editor.
5. Wait while the coach is generated. The screen shows progress messages and the note "This can take a few minutes. Please don't refresh or close this window."
6. When **Coach ready!** appears, a live preview of the draft opens. Try the coach, then select **Publish** to make it live, or **Continue to Editor →** to refine it first.
7. In the editor, work through the **Design** stage section by section (see The coach editor below), and select **Save Changes** in each section you change.
8. Open the **Test** stage and hold a conversation with the coach yourself.
9. Select **Publish** in the editor header.
10. Open the **Publish** stage and copy the link or embed code for where the coach will run.

## Result

You have a published coach with its own link and embed codes. Learners who open it see the coach's welcome message, or a debrief of a linked simulation or evaluator they have completed. To connect the coach to simulations and evaluators, see [Linking a coach to simulations and evaluators](https://docs.devlin.ai/coaches/link-coaches-to-simulations-and-evaluators).

## The Create New Coach screen

The **New coach** link on **Publish → Overview** opens the full **Create New Coach** screen. If a generation started from the Studio dialog fails, you are also returned to this screen with your description filled in. It has the same description field, limited to 10,000 characters, and adds:

- **Coach Name** (optional): the name of the coach in your library, up to 120 characters. If you leave it empty, devlin.ai titles the coach for you.
- Source materials, on the Core, Team, Enterprise plans (see What generation creates below).

Its buttons are **Generate Coach** and **Start from scratch**. From this screen, **Start from scratch** names the blank draft "Untitled Coach" unless you typed a **Coach Name**.

## What generation creates

Generation writes a complete draft from your description: the library name (unless you typed one), the coach's own name, its role, its personality, a guidance level, custom instructions, a welcome message, and optionally reference content. The guidance level it picks is applied to both **Real-time guidance** and **Debrief guidance**; you can set them apart in the editor.

- Pairing with simulations: devlin.ai gives the generator a list of your most recent simulations. When your description asks for the coach to be paired with some of them, the coach is linked to those simulations, and its persona and welcome message are written around what they practice. If the description does not mention pairing, the generator is told to link nothing.
- Source materials: on the Core, Team, Enterprise plans you can attach up to 5 documents or links for the draft to be built from. On the **Create New Coach** screen, **Generate Coach** waits until they have finished processing unless you choose to generate without waiting. On other plans the form shows a note about the plan instead of the upload area.
- Draft only: a generated coach is always a draft. It is saved as soon as it is generated, so it is in your library even if you leave the preview without choosing a button.

### What generation costs

Under the button the form says "Generation uses credits based on input length". The charge is the actual usage of the generation: your description, any attached source materials and the list of your simulations on the way in, and the generated draft on the way out. Before it starts, devlin.ai reserves the most the generation could cost and checks that your balance covers it. Afterwards you are charged what was used and the rest of the reservation is released.

- If the balance does not cover the reservation, nothing is generated and the form shows "Not enough credits to generate." with a **Purchase more credits** link.
- If generation fails after it has started, the form shows "Generation failed. Please try again." The credits the failed attempt already used are still charged.
- A workspace can start 10 generations an hour, counting simulations and coaches together and including attempts that fail. Past that, the form shows "Too many generations. Please try again later."

## The coach editor

The editor has these stages: **Design**, **Test**, **Publish** and **Results**. The **Design** stage is split into sections: **Personality**, **Content**, **Linked Sims**, **Knowledge**, **Variables**, **Start screen** and **Visual Editor**.

The header shows the coach's library name, its status (draft or published), and buttons for **Undo**, **Redo**, **Version history**, **Delete coach** and **Publish** or **Unpublish**.

### The library name

The name in the editor header is the coach's name in your library. Click it to edit it. It saves when you click away from the field, with no **Save Changes** step. It can be up to 120 characters, and a blank name is not saved: the field goes back to the saved name. Learners do not see this name in the conversation; they see the coach's own name, set in the **Personality** section.

### Personality

The **Personality** section holds the **Personality & Behavior** card.

- **Coach Name**: what the coach is called. The coach is told this is its name.
- **Role**: the coach's title or position. The coach's instructions open with this name and role, so fill in both.
- **Personality**: how the coach sounds and behaves, such as tone, mannerisms and backstory.
- **Welcome Message**: the coach's first message when a learner opens it and there is no completed result to debrief. A coach started from scratch starts with "Hi! I'm here to help. Ask me anything."
- **Enable voice mode**: lets learners talk to the coach. See [Setting up voice for a simulation or coach](https://docs.devlin.ai/voice/set-up-voice).
- **Real-time guidance** and **Debrief guidance**: see Guidance levels below.
- **Session Ending**: see Ending a coaching session below.

### Guidance levels

A coach has separate guidance levels for real-time help and for debriefs:

- **Debrief guidance** applies to the debrief message the coach writes when a linked simulation or evaluator result arrives. In a text conversation, the learner's replies after that message are answered with **Real-time guidance**, like every other message. A voice session that opens on a debrief uses **Debrief guidance** for the whole session.
- **Real-time guidance** applies to every other reply: while the learner is in a linked simulation, and when the learner talks to the coach with no simulation running.

Each one is set to one of these levels:

| Level | What the coach does |
|---|---|
| **Coaching** | Asks probing questions and helps the learner find the answer, without giving it directly. |
| **Supportive** | Offers suggestions and explains its reasoning while the learner stays in control. |
| **Direct** | Says plainly what to do, briefly, with a short example phrase only when it makes the action clearer. |
| **Informative** | Teaches and explains concepts step by step, with examples and analogies. |

A coach started from scratch has **Direct** for real-time guidance and **Coaching** for debriefs.

When the learner is in a live voice simulation, the coach is also told to keep its real-time replies short and spoken in style whatever level you chose, because the character in the simulation is waiting.

### Content

The **Content** section holds the **Content & Instructions** card.

- **Knowledge & Reference Material**: concepts, frameworks or guidelines the coach should know. The coach uses it as background, and it is not sent to learners directly. It holds up to 10,000 characters, and a counter under the field shows how many you have used.
- **Custom Instructions**: additional behavior rules for the coach.

For larger bodies of material, link a knowledge base in the **Knowledge** section instead. See [Grounding simulations and coaches in a knowledge base](https://docs.devlin.ai/knowledge/ground-simulations-and-coaches-in-knowledge).

### What the coach always does

Whatever you write, the coach is also told to be concise, to write plain text without formatting, and to respond the way a real coach would in conversation. When it has a simulation transcript to work from, it is told the learner cannot see that transcript, so it quotes or paraphrases a moment instead of telling the learner to look it up. The exception is a linked simulation with the transcript viewer turned on: in a text conversation the coach is told the learner can open that transcript. See [Linking a coach to simulations and evaluators](https://docs.devlin.ai/coaches/link-coaches-to-simulations-and-evaluators).

### The other Design sections

- **Linked Sims**: which simulations and evaluators the coach works with. See [Linking a coach to simulations and evaluators](https://docs.devlin.ai/coaches/link-coaches-to-simulations-and-evaluators).
- **Knowledge**: see [Grounding simulations and coaches in a knowledge base](https://docs.devlin.ai/knowledge/ground-simulations-and-coaches-in-knowledge).
- **Variables**: the custom variables and system variables the coach writes into a Storyline course, including the completion variable (`Coach_Complete` unless you rename it). A coach has no evaluation, so it has no result variables. See [Storyline variables a simulation or coach writes](https://docs.devlin.ai/publish-and-embed/storyline-variables).
- **Start screen**: see [The start screen learners see first](https://docs.devlin.ai/simulations/start-screen).
- **Visual Editor**: colors, sizes, branding and the character portrait. See [Appearance and branding](https://docs.devlin.ai/simulations/appearance-and-branding).

## Ending a coaching session

A coach's conversation is open-ended unless you give it a way to end.

### End conditions

Under **Session Ending** in the **Personality** section, describe when the session should end, for example when the learner says they are ready to wrap up. Select **+ Add End Condition** to add another. The session ends when any one of the conditions is met. Empty conditions are dropped when you save. With no end condition and no turn limit, a text conversation does not end by itself.

When a condition is met in a text conversation, the coach sends its last reply, the message box is replaced by a notice that the session has ended, and the coach sets its completion variable to true. The notice, and what happens when the learner comes back, are covered in [Coach sessions across slides, reloads, and course restarts](https://docs.devlin.ai/coaches/coach-sessions-and-restarts).

### Turn limit

A coach can also have a turn limit. It is not set by default, and the editor has no field for it: it is set from an AI tool (see Working from an AI tool below). The limit must be a positive whole number, and setting it to zero removes the limit; a negative or fractional value is refused with "The turn limit must be a whole number of 1 or more."

In a text conversation a turn is one message from the learner. The coach's welcome message and its debriefs do not count. When the learner's message reaches the limit, the coach answers it and the session ends in the same way as an end condition. If a message reaches the coach after the limit, the coach does not answer and shows "Conversation limit reached."

## Settings without an editor field

These coach settings are stored on the coach but have no control in the editor. An AI tool connected to the workspace can read and change them (see Working from an AI tool below).

- Turn limit (`max_turns`): described above. Off by default.
- Automatic debrief (`dynamic_opening`): on by default. When it is on, no simulation is running, and the learner has completed a linked simulation or evaluator with its debrief option on that the coach has not yet debriefed, the coach opens with a debrief of that result instead of the welcome message. When it is off, the coach never starts a debrief by itself and opens with the welcome message.
- Simulation complete message (`sim_complete_message`): empty by default. When it is set, the coach adds this message to its conversation at the moment a simulation the learner was running in the same course page or browser ends. When it is empty, nothing is added.

## Saving and unsaved changes

- The editor does not save automatically. **Personality**, **Content**, **Variables**, **Start screen** and **Visual Editor** each have their own **Save Changes** button, and Cmd+S (Ctrl+S on Windows) saves the section you are looking at. The button reads **Saved!** for a moment when the save succeeds.
- **Linked Sims** and **Knowledge** save each change as you make it. The **Daily Credit Cap** card in the **Publish** stage has its own **Save** button and is not part of the unsaved-changes dialog.
- If you switch stage or section, use the back arrow or the **Coaches** breadcrumb, or switch workspace with unsaved changes, a dialog asks you to save or discard them. Saving from the dialog saves every section that has unsaved changes.
- Closing or reloading the browser tab with unsaved changes triggers the browser's own leave-page warning.
- **Undo** and **Redo** step back and forward through your edits across all sections. While your cursor is in a text field, the keyboard shortcut undoes typing in that field instead. If an undo changes a section you are not looking at, a notice offers **Go to section**.
- Saves to the coach's content and settings are recorded in its version history. The character portrait, the daily credit cap, the knowledge base choices and the folder are not part of a version. See [Version history, undo and restoring a version](https://docs.devlin.ai/simulations/version-history).
- If the coach is published, saved changes apply to the live coach without republishing. Changes to what the coach says apply from the learner's next message; changes to the welcome message, appearance, start screen and variable names reach learners after a short cache delay. Saving a change to the text covered by the content check (see Publishing below) runs the check again, and a rejected change is not saved. The section shows the reason, which starts "This update was rejected:", and still counts as unsaved.

## Testing a coach

The **Test** stage runs the coach in a live preview. It works on drafts, and it always shows the coach as it was last saved. Preview conversations use credits like real sessions and are recorded as test runs, separate from learner sessions. The preview link is temporary and valid for 60 minutes; once it has run out, the preview shows "This preview has expired. Reload the page to continue." The **Test** stage uses the same preview panel as the simulation editor. See Testing in the live preview in [Building a simulation](https://docs.devlin.ai/simulations/build-a-simulation).

The preview shown after generation works the same way. If it cannot load, the screen shows **Preview unavailable**; the draft is saved and you can still continue to the editor.

## Publishing

A coach is either a draft or published. Learners can open only a published coach.

Select **Publish** in the editor header. While the request runs the button reads "Publishing…". When it succeeds, the status next to the name changes to published and the button becomes **Unpublish**. Publishing uses the coach as it was last saved, so save your sections first. Each publish is recorded in the version history.

You can also publish and unpublish coaches from **Publish → Overview**. See [Publishing a simulation and sharing its link](https://docs.devlin.ai/publish-and-embed/publish-a-simulation).

### The content check

Publishing runs an automated content check on the text you wrote for the coach: the coach's name, role, personality, custom instructions, reference material, welcome message and simulation complete message, plus its end conditions, custom variables and mood trigger.

The check is built for workplace learning. It allows direct, blunt or demanding coaching personas, sensitive professional topics, reference material about conflict or mistakes, and negative examples used to teach what not to do. It blocks a coach designed to:

- produce sexual or romantic content
- train people in fraud, scams or illegal activity
- promote hate speech or harassment as the goal, as opposed to subject matter the coach helps learners handle
- impersonate a real, specific public individual

What you see when the check does not pass:

- The content is rejected. The coach stays a draft. The editor shows "Could not publish coach" with a message that starts "This coach could not be published:" and gives the reason. Edit the content the reason points to, save, and publish again.
- The content is too long to check. When the checked text adds up to more than 20000 characters, publishing is refused and the reason asks you to reduce the length of the coach fields.
- The check is unavailable. The coach is not published and the reason reads "Content moderation is temporarily unavailable. Please try again in a moment." Nothing is wrong with your content; publish again shortly.
- The coach kept changing while the check was running. A save during the check makes the check run once more on the new text. If the coach is saved again during that second check, publishing stops and the message reads "The coach was edited while it was being reviewed. Please publish again."

A check that already passed is not repeated when you publish the same text again.

Unlike a simulation, a coach with voice turned on is not held back from publishing by its voice setup. See [Setting up voice for a simulation or coach](https://docs.devlin.ai/voice/set-up-voice).

### Unpublishing

Select **Unpublish** in the editor header and confirm. The confirmation says "Learners lose access to its link and embeds until you publish again. Your content is kept and can be republished any time." Unpublishing is recorded in the version history and does not change the coach's link, so links and embeds you have handed out work again when you publish again.

### What learners see when a coach is not published

A learner who opens the link or embed of a draft or unpublished coach for the first time, or a link that matches no coach, sees "Coach not found or not available." There is no retry link on this screen; the learner reloads the page after you publish. A learner who already had the coach open when you unpublished it, or who returns to its slide in the same course sitting, gets "Failed to send message. Please try again." on their next message.

## Links and embed codes

The **Publish** stage shows the coach's links once it is published. For a draft it shows only "Publish your coach first to get its links, embed codes, and LMS package."

- **Daily Credit Cap**: shown to workspace owners and admins, for drafts too. See [Daily spending caps for simulations and coaches](https://docs.devlin.ai/plans-and-billing/daily-spending-caps).
- **Standalone link**: a full-screen coach on its own page, for sharing directly. **Copy URL** copies it.
- **Storyline 360**: the address to paste into a Web Object in Articulate Storyline. See [Embedding a simulation in Articulate Storyline](https://docs.devlin.ai/publish-and-embed/storyline-web-object-setup) for the Web Object steps and [Storyline variables a simulation or coach writes](https://docs.devlin.ai/publish-and-embed/storyline-variables) for the variables.
- **Rise 360**: an embed snippet for an Articulate Rise lesson. Set **Height (px)**, from 200 to 2000 with 600 as the starting value, then select **Copy Snippet**. See [Embedding a simulation in Rise 360](https://docs.devlin.ai/publish-and-embed/rise-360).
- **LMS package**: a SCORM or xAPI package, on these plans: Core, Team, Enterprise. See [LMS packages: SCORM and xAPI reporting](https://docs.devlin.ai/publish-and-embed/lms-packages-scorm-and-xapi).

When voice is turned on for the coach, the **Standalone link**, **Storyline 360** and **Rise 360** cards each show a **Text variant** and a **Voice variant**. See [Letting learners switch between text and voice](https://docs.devlin.ai/voice/text-and-voice-mode-switching).

## Deleting a coach

**Delete coach** in the editor header asks you to confirm, then permanently removes the coach and its links to simulations and evaluators. This cannot be undone.

## Limits

- devlin.ai sets no limit on the number of coaches in a workspace, on any plan.
- The reference material in the **Content** section holds up to 10,000 characters. A longer value is refused when saving.
- A workspace can start 10 simulation and coach generations an hour, including attempts that fail.

## Working from an AI tool

If your workspace has the [MCP server](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) turned on, a connected AI tool can work with the same coaches:

- `list_coaches` lets an AI tool list the workspace's coaches, most recently edited first, with each one's status, to find the one to work on. It returns up to 100 coaches.
- `get_coach` lets an AI tool read one coach's configuration, its linked simulations and evaluators, and the list of fields it is allowed to change with their current values.
- `create_coach` lets an AI tool create a new draft coach from a name and optional starting values. The draft cannot be opened by learners until it is published.
- `update_coach` lets an AI tool change a coach's fields. Changes to a draft apply immediately. Changes to a published or archived coach need an explicit confirmation from the tool and go through the content check again, and if your workspace requires in-app approval for live changes, the change waits for an owner or admin to approve it.
- `set_coach_publish_state` lets an AI tool publish or unpublish a coach. The tool must confirm the call explicitly. Publishing goes through the same content check, and if your workspace requires in-app approval for live changes, the call records a change request for an owner or admin to approve instead of applying it. The tool cannot publish an archived coach.

An AI tool can change the library name, the coach's name, role and personality, both guidance levels, the custom instructions, welcome message and reference material, the end conditions, the variables, the colors and the folder, and also the turn limit, the automatic debrief and the simulation complete message, which have no field in the editor. It cannot change the start screen or the character portrait, turn voice on or pick a voice; those are done in the editor.

## Related

- [Linking a coach to simulations and evaluators](https://docs.devlin.ai/coaches/link-coaches-to-simulations-and-evaluators)
- [Coach sessions across slides, reloads, and course restarts](https://docs.devlin.ai/coaches/coach-sessions-and-restarts)
- [Grounding simulations and coaches in a knowledge base](https://docs.devlin.ai/knowledge/ground-simulations-and-coaches-in-knowledge)
- [Setting up voice for a simulation or coach](https://docs.devlin.ai/voice/set-up-voice)
- [Storyline variables a simulation or coach writes](https://docs.devlin.ai/publish-and-embed/storyline-variables)
- [Results for one simulation or coach](https://docs.devlin.ai/results-and-analytics/results-for-a-simulation-or-coach)
- [MCP server and AI tool connectors](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors)