> For the complete documentation index, see [llms.txt](https://docs.siminsights.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.siminsights.com/spark/scoring-and-feedback.md).

# Scoring and feedback

Using agents to write feedback for a learner and score them against a competency model.

Agents analyze the conversation and produce outputs. They watch the conversation, grade the learner, and provide feedback based on a rubric. Their outputs populate feedback templates and, when scoring is enabled, write to user-attribute scores. An agent runs when the learner hits "End" during their run through.

{% hint style="info" %}
Scoring a learner's skills needs approval on your account, and new competency models are built by SimInsights on request. Email <support@siminsights.zendesk.com> to ask for either.
{% endhint %}

## Agent settings

In the **Agents** section of the AI tab, **Create agent** adds an agent, the dropdown switches between agents, and **Delete** removes the selected one. Each agent's **Configuration** has:

* **Name**: the agent's name.
* **When it runs**: On session end. Agents run automatically when the learner ends the session.
* **Language model**: GPT-5, GPT-4o, GPT-4o mini or Gemini 2.5 Flash. See [Large Language Models & Data Privacy](https://docs.siminsights.com/hyperskill-studio-authoring/ai-features/large-language-models-and-data-privacy).
* **Use history**: Lets the agent use the chat history.

## Feedback for the learner

Two steps: the agent produces the feedback and the scenario flow decides where it appears.

{% stepper %}
{% step %}

### Give the agent an output

Create an agent and add an output with **Destination** set to **Display only**.

**Description** is how the AI knows what to write, for example *2 bullet points naming what to work on*. You can put that guidance here or in the agent's base prompt.

**Reference name** is how you point at this output later.

<figure><img src="https://2704613365-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYaaXoZ4YGbVdAnAhdcE%2Fuploads%2FDEfC2YcNvwE7R97CSbz8%2Fimage.png?alt=media&#x26;token=19177435-fe22-476f-b845-549c7a6af5a8" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Reference it in the feedback panel

You can reference the AI's analysis/provided feedback so that the learner can receive feedback at the end of their session. In this example it is referenced as `<Agent.SalesEvaluationAgent.coaching_summary>`. The copy icon next to the reference name copies the exact text.

<figure><img src="https://2704613365-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYaaXoZ4YGbVdAnAhdcE%2Fuploads%2FCWChrWbh3Jk8toIxTA5E%2Fimage.png?alt=media&#x26;token=3f13b0fa-c1d8-4641-a568-c0219c615a90" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Scoring a skill

A competency model is a tree of skills a learner can be measured against. See [Competency models](https://docs.siminsights.com/scoring-and-mastery/competency-models).

{% stepper %}
{% step %}

### Attach a competency model

Choose the model you want the Spark scored against.
{% endstep %}

{% step %}

### Add an output the agent scores on

The agent judges the conversation against that skill and writes a value. To do this, add a User Attribute output to the agent.
{% endstep %}
{% endstepper %}

The result lands on the learner's run in HyperSkill Platform, next to scores from 3D simulations. See [How scores work](https://docs.siminsights.com/scoring-and-mastery/how-scores-work).

## Seeing the results

A Spark's analytics work like any simulation's: how many learners completed it, average completion time, completion rate and average mastery, then a table of individual runs. **Device** reads Web (Spark).

Opening a run shows the learner's skill mastery and how it moved, the session narrative of what they said and what the character said back, and the raw event log. See [Simulation analytics](https://docs.siminsights.com/analytics/simulation-analytics) and [Run detail](https://docs.siminsights.com/analytics/run-detail).