# Linking a coach to simulations and evaluators

> Link a coach to simulations and evaluators so it can help during a live simulation and debrief the learner's results afterwards.

- Plans: All plans
- Canonical: https://docs.devlin.ai/coaches/link-coaches-to-simulations-and-evaluators

A coach on its own knows nothing about what a learner did elsewhere in the course. Linking it to a simulation or an evaluator lets the coach read that learner's work: it can help while a linked simulation is running, and it can debrief the result once a linked simulation or evaluator submission is finished. Links are available on every plan, and any member of the workspace can add, change or remove them.

## Before you start

- You need a coach. See [Building and publishing a coach](https://docs.devlin.ai/coaches/build-a-coach).
- The simulation or evaluator must be in the same workspace as the coach. Linking to an item in another workspace is refused.
- The linked item does not have to be published. You can link a draft, and the link row shows the item's current status. Learners can only reach the coach once the coach itself is published.
- There is no limit on the number of links. A coach can link to many simulations and evaluators, and a simulation or evaluator can be linked to more than one coach. Each coach debriefs an attempt independently.
- A debrief opens automatically only when the coach's automatic debrief setting (`dynamic_opening`) is on, which is the default. See [Building and publishing a coach](https://docs.devlin.ai/coaches/build-a-coach).

## Steps

1. Open **Studio**, select **Coaches**, open the coach, and stay on the **Design** stage.
2. Open the **Linked Sims** section. It has a **Linked Simulations** list and, below it, a **Linked Evaluators** list.
3. Select **+ Link a Simulation**. Under **Select a simulation**, choose the simulation. Simulations that are already linked are left out of the list. When none remain, the picker shows "All simulations are already linked."
4. Set the options on the new link. Each change saves as soon as you make it, including on a published coach. The real-time options apply from the learner's next message; **Post-sim debrief** and **Learners can view the transcript** apply from the next time the coach loads its context.
   - **Real-time guidance** (on by default): the coach can see the simulation conversation as it happens and help the learner during it.
   - **Post-sim debrief** (on by default): the learner's finished attempt becomes context for the coach, and the coach can discuss the result.
   - **Learners can view the transcript** (off by default): adds a transcript link to the coach's text chat so learners can reread their finished conversation in the **Simulation transcript** viewer.
   - **Share grading criteria during live sims** (on by default): during real-time help the coach also sees what the simulation is evaluated on. This option is unavailable while **Real-time guidance** is off.
5. To link an evaluator, select **+ Link an Evaluator** and choose it under **Select an evaluator**. An evaluator link has a single option, **Debrief results** (on by default): the learner's scored submission becomes context for the coach.
6. To unlink, select **Remove** on the link row. The link is removed immediately, with no confirmation.

If a link change cannot be saved, the editor shows "Could not update the link" and leaves the option as it was.

Links are not part of the coach's version history. Restoring an earlier version of a coach does not bring back or remove a link.

## Result

### What the coach reads from a linked simulation

With **Post-sim debrief** on, the coach receives, for the learner's finished attempt:

- The evaluation result: pass or fail, the percentage score and the written feedback. If a reviewer adjusted the result, the coach gets the adjusted outcome. For a feedback-only evaluation the coach gets the written feedback and is told never to mention a score or pass or fail. See [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring).
- A short summary of the conversation, once one exists. It is generated automatically the first time the coach loads the attempt. When the attempt has an evaluation result, the summary is written in the background and reaches the coach from the next time it loads its context. Generating it uses a small amount of credits; see [Credits and usage](https://docs.devlin.ai/plans-and-billing/credits-and-usage).
- The conversation transcript. The 8 most recently finished simulations each contribute a full transcript, trimmed to its most recent 150 messages. Older ones contribute their summary and evaluation result only.
- The evaluation criteria with their points, any penalties, and the passing score, when the simulation has evaluation turned on and at least one criterion. For a feedback-only simulation the criteria are given without points or a passing score.
- For the debrief message itself, how the learner was rated on each criterion, with the points earned and the reason given.

With **Real-time guidance** on, each message the learner sends to the coach while the simulation is running carries the live conversation so far. The coach is told the simulation is still active and that it must not reveal outcomes. With **Share grading criteria during live sims** on, the coach also gets the criteria and penalties as things the learner should aim for or avoid, without points or a passing score, and is told not to read them out. If the simulation has evaluation turned off or has no criteria, that option does nothing.

If **Real-time guidance** is off, the coach is not told about the running simulation at all. The coach only sees a running simulation that is linked to it. The simulation and the coach must be open at the same time in the same course page or the same browser for the coach to follow it.

Real-time guidance is always given in text, even for a coach with voice turned on. See [Setting up voice](https://docs.devlin.ai/voice/set-up-voice).

### What the coach reads from a linked evaluator

With **Debrief results** on, the coach receives the learner's final result from that evaluator:

- Pass or fail, the percentage score and the written feedback. If a reviewer adjusted the result, the coach gets the adjusted outcome.
- The combined result, when the evaluator is linked to a simulation and a final combined score exists.
- The evaluator's criteria, when it has at least one.
- For the debrief message itself, the rating on each criterion and the learner's submitted work, field by field, as it was scored.

Evaluator links have no real-time option because an evaluator is a form, not a live conversation. For how evaluators score work, see [Evaluators](https://docs.devlin.ai/evaluators/evaluators-scoring-submitted-work).

### Which attempts count

- Only finished simulation conversations count. Test runs are left out for learners. In a preview of the coach, it reads your test runs of the linked simulation instead.
- The coach uses a single attempt per linked simulation and a single final result per linked evaluator.
- When the coach runs inside a course that reports a course sitting (a sitting lasts until the course page is reloaded), the coach uses the most recent attempt from the current sitting. An attempt from an earlier sitting is used only if this coach has not debriefed it yet and it finished within the last 60 minutes. This keeps a fresh coach from commenting on an old attempt.
- When no course sitting is reported, the coach uses the learner's most recent finished attempt.

### How the learner is matched

The coach, simulation and evaluator embeds share a learner id that is generated in the learner's browser, kept in that browser's storage, and shared through the host course page. The coach asks for finished attempts recorded under that id. An evaluator result is also matched when it was submitted in the same course sitting.

The match does not use a name or identifier the learner types in. A learner who completes a simulation in one browser and opens the coach in another is not matched, and the coach behaves as if there is no linked attempt. To collect names or identifiers for reporting, see [Collecting learner identity](https://docs.devlin.ai/workspace-and-team/learner-identity).

### What the learner sees

- No linked attempt yet. The coach opens with its welcome message.
- A finished attempt the coach has not debriefed. With the automatic debrief on and no simulation running, the coach opens with a debrief instead of the welcome message. For a scored result it states the outcome, then discusses specifics from the learner's performance; for a result with no score it goes straight to the specifics. If several results are waiting, the coach gives one debrief that covers each of them.
- A result arrives while the coach is open. When a linked simulation's evaluation completes or a linked evaluator is submitted, the coach posts the debrief into the current conversation without a reload.
- A retake. A new attempt is debriefed again. An attempt is debriefed once per coach, so reloading the page does not repeat a debrief.
- Automatic debrief off. No debrief is posted. The coach still has the result, feedback, summary, transcript and criteria as context when the learner asks about it, but not the rating on each criterion or the evaluator submission, which are supplied only for the debrief message.
- The debrief cannot be generated. A coach with no conversation yet falls back to its welcome message.

A coach with voice turned on can deliver the debrief in a voice session. See [Voice sessions](https://docs.devlin.ai/voice/voice-sessions-and-course-controls).

If the coaching session has ended, a new result reopens it. See [Coach sessions across slides, reloads, and course restarts](https://docs.devlin.ai/coaches/coach-sessions-and-restarts).

### The transcript viewer

With **Learners can view the transcript** on, a transcript link appears above the coach's chat once the learner has a finished attempt for that simulation. It opens the **Simulation transcript** viewer in place of the chat, and the learner can go back to the conversation at any time. In a voice session the viewer opens beside the call.

- The viewer shows the learner's turns and the character's turns in full. It is not trimmed the way the coach's own copy is.
- It follows the same attempt rules as the debrief, so it shows the attempt the coach is working from.
- If several linked simulations have the option on, the viewer has a tab for each and opens on the most recently finished one.
- The link is hidden while a simulation is running.
- The option works independently of **Post-sim debrief**. You can show the transcript for a simulation the coach does not debrief.

### Unpublishing and deleting

- Unpublishing or archiving a linked simulation or evaluator does not remove the link. The coach keeps using attempts that learners already finished.
- Deleting a simulation, an evaluator or a coach deletes its links with it.
- Turning **Debrief results** off, or removing an evaluator link, stops that evaluator's result from reaching the coach from the learner's next message. Turning **Post-sim debrief** off, or removing a simulation link, stops that simulation's results from the next time the coach loads its context.

For what moving and duplicating do to links, see [Organizing Studio with folders](https://docs.devlin.ai/get-started/organize-studio-with-folders).

### Context depth

A coach stores a `context_depth` value, `summaries` (the default) or `full_transcripts`. It has no control in the editor and no effect on what the coach reads: the coach always receives the summaries and transcripts described above, whichever value is stored.

### From an AI tool

An AI tool connected through the [MCP server](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) can link, update and unlink a simulation with `manage_coach_simulation_link`, including each of the link options. Options it does not name keep their current values.

It can link, update and unlink an evaluator with `manage_coach_evaluator_link`, including the debrief option.

Both tools can preview a change without writing it, and both require an explicit confirmation when the coach is published.

## Related

- [Building and publishing a coach](https://docs.devlin.ai/coaches/build-a-coach)
- [Coach sessions across slides, reloads, and course restarts](https://docs.devlin.ai/coaches/coach-sessions-and-restarts)
- [Evaluators](https://docs.devlin.ai/evaluators/evaluators-scoring-submitted-work)
- [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring)
- [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)