# Diagnose and improve

> Works out why an agent didn't do what you expected, and stages a fix as a version you test before it goes live.

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

Running an agent is a loop: see what happened, diagnose what went wrong, change the agent, test the change, activate it, then see what happens next. Highlighted: Diagnose.

## Ask your AI client

```
The invoice exceptions agent registered a supplier query on INV-4471, and the contract allows that difference. Find out why, and save a fix as a new version for me to test. Don't activate anything.
```

Skill: [mindset-test-agent](https://docs.mindset.ai/skills/mindset-test-agent/SKILL.md)

## What you get back

A named cause, the run that shows it, and a fix saved as a new [version](https://docs.mindset.ai/docs/versions-and-going-live) that isn't live. Saving puts nothing in front of people. Activating does, and that stays your call.

## Which of eight things happened

Start at the top. Most reports of "the agent is broken" are settled in the first three.

| What you see                         | Usually                                                                                 | Fix                                                                                        |
| ------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| No output at all                     | It never ran                                                                            | The trigger, not the agent. Check the schedule is on in the active version                 |
| It ran and nothing changed           | A write is still pending approval, or a script's `$ask` is waiting on a person          | [Approve the write](https://docs.mindset.ai/docs/approve-what-an-agent-can-do), or answer the question            |
| It stopped part way                  | A phase's exit condition didn't hold, or the turn reached a limit                       | Reword the condition so a real answer can meet it. See [Runs](https://docs.mindset.ai/docs/runs) for limits       |
| It finished and the answer is wrong  | A condition can be met without the work                                                 | Tighten the condition so meeting it needs the work, such as naming a contract clause       |
| It did something too early           | That phase held the operation                                                           | Take the write operation off every phase except the last                                   |
| An error naming an outside system    | The credential expired, or is scoped too narrowly                                       | Replace it on the connection, then run one read on its own                                 |
| Plausible output built on wrong data | The connection points at the wrong account, or a function reads fields that don't exist | Check the account, then run the function on one invoice and see which step returns nothing |
| Right most times, wrong sometimes    | Too much left to the model                                                              | Split the phase, say the number, add a judged gate where quality matters                   |

When the answer is right and the numbers aren't: a slow tail on a connection the agent calls means the outside system is slow, and no prompt change fixes it. A high **Avg input tok/call** means it sends too much. See [See and control cost](https://docs.mindset.ai/docs/see-and-control-what-it-costs).

> **Tip:** If a phrase in the prompt needs a definition before someone else could apply it the same way every time ("a material discrepancy"), move that definition into a [function](https://docs.mindset.ai/docs/functions). Then every run applies the same rule.

## What you decide

- Whether the cause is the one you'd stake the fix on. Change one thing at a time, or you won't know which fix worked.
- Whether to stop it now. **Withdraw approval** on a write, or **Disable** on a connection, takes effect on the next call. See [Approve what agents can do](https://docs.mindset.ai/docs/approve-what-an-agent-can-do).
- Whether to re-run a run that stopped part way. A write happens when it's called, so check what it already changed first.

## Done when

- You named which of the eight it was before you changed anything.
- The fix is a saved version, [tested](https://docs.mindset.ai/docs/test-an-agents-behavior), then activated.
- An acceptance test now covers the failure. **Save as acceptance test** on the session drafts one from the real conversation.

## In the Studio

Open the session in **Log → Sessions** and read **Steps**, the run record for that conversation. Make the fix by telling the **Agent Builder**, docked on every tab of the agent, what to change. **Save as version** records it, and **Activate** on **Versions & Availability** puts it live.

![The Steps tab of a session in the Log.](https://docs.mindset.ai/images/docs/studio/session-steps.png)