# Runs

> A run is one execution of an agent, from what started it to how it ended.

**Skill for your coding agent:** [`mindset-server-api/SKILL.md`](https://docs.mindset.ai/skills/mindset-server-api/SKILL.md)

**Skill for your coding agent:** [`mindset-script/SKILL.md`](https://docs.mindset.ai/skills/mindset-script/SKILL.md)

**Skill for your coding agent:** [`mindset-human-in-the-loop/SKILL.md`](https://docs.mindset.ai/skills/mindset-human-in-the-loop/SKILL.md)

Builders work from a coding agent and operators from an AI client, both through the MCP server, or in the Studio. In Mindset, an agent is a prompt and a model, held to an order by a script when needed. It uses connections to outside systems, operations on them, functions and widgets. Every change is a version, and every execution is a run. Every piece sits on one security and compliance layer: the org sets its posture once, and every agent works under it, with the audit trail and, once an admin turns it on, personal data redaction. The platform runs in your own cloud (AWS, GCP or Azure) or is hosted by Mindset. Your app reaches agents through the SDK, your server through the API, and people through the Hub and schedules. Highlighted: Run.

A **run** is one execution of an [agent](https://docs.mindset.ai/docs/agents), from what started it to how it ended. A person in chat, a schedule, a webhook, your own software through the API, or another agent can [start one](https://docs.mindset.ai/docs/how-agents-are-started-and-reached).

A run is made of **turns**. In a turn the agent is asked, calls what it needs and answers. A run that follows a [script](https://docs.mindset.ai/docs/scripts) also records the phase it's in and the phases it passed through.

## Why it matters

When someone asks what an agent did, its runs answer: which version ran, what it called and why it stopped. A run waiting on a person spends nothing while it waits.

## What's recorded

**Log** holds each session and its events, with the version that ran, tokens, duration and who acted. The agent's **Triggering** tab lists each scheduled, manual or webhook run and where its script got to: **Completed**, **Waiting on a person** or **Stopped mid-flow**. Each **Chat** reply says "Answered by version N".

> **Info:** Mindset writes the run's record, not the agent, so no agent can leave a call out. Admins' changes, such as approvals and settings, go into the separate audit record. See [Compliance](https://docs.mindset.ai/docs/compliance).

## When a turn reaches a limit

Every turn works inside [limits](https://docs.mindset.ai/docs/limits) on time, model rounds, tokens and repeated calls. A turn that reaches one stops where it is, keeps everything it did, and records `step_limit`, `deadline`, `spend_limit` or `repetition`. It stays in its phase, even one ready to move on, and the record says `bound`. (`held` means the phase's exit condition wasn't met.)

| Started by                                  | How it continues                                                                                                                                          |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A person in chat                            | When they send another message                                                                                                                            |
| A schedule or a webhook, following a script | Mindset gives it another turn later, from the phase it was in. A firing that runs out of turns, time or tokens shows **Stopped mid-flow** with the reason |
| Your software through the API               | When it posts another message to the same conversation. Nothing carries it on by itself                                                                   |

## Waiting on a person

1. **A script phase asks a person something**: The run stays in that phase.
2. **Waiting on a person**: The run is **parked**: it holds no turn and spends nothing.
3. **The answer comes, or the wait the author set runs out**
4. **The run resumes from that phase**: With a fresh turn budget: on its own if a schedule or webhook started it, or on the next message otherwise.

## When Mindset itself fails

A run isn't lost when the server driving it stops. Mindset picks it up again and runs any of the phase's entry steps that hadn't finished. [Limits](https://docs.mindset.ai/docs/limits) says when a parked or failing run is closed as abandoned.

## Writes aren't undone

> **Danger:** A write happens when the agent calls it, so a run that stops part way may already have changed something.

The invoice exceptions agent reads in its first three phases and writes only in the last, so a run that stops before then has changed nothing.

## Calling twice doesn't run twice

Your software can pass an idempotency key when it starts a conversation, and the same key returns the first conversation. Each slot on a schedule fires once.

To read a run, see [See what happened](https://docs.mindset.ai/docs/check-what-happened).