> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-improvement

> On a schedule, the Builder agent reviews your workspace's chats, improves its skills, prompts, knowledge and tests on a copy of production, and suggests the changes for you to apply or dismiss.

> [!NOTE]
>
> Self-improvement is a **Beta** feature.

Your users find the gaps in your agent's context faster than you can: the term nobody defined, the table the agent keeps guessing at, the chart it can't draw. Self-improvement turns those conversations into fixes without you having to read them all.

On a schedule you choose, the [Builder agent](https://docs.upsolve.ai/ai-agent-builder/builder-agent.md) reviews the workspace's recent chats, works out what went wrong, and edits the workspace's skills, prompts, knowledge base and tests to fix it. It does this on a **copy of production**, so your draft and your live agent are untouched. When it's done, you get a report of what it found and the changes it suggests, and you decide: **apply** them to your draft, or **dismiss** them.

![The Self-improvement page showing it is Active with the next run time, an overview of runs needing review, suggested and applied, the monthly budget used, and a list of past runs](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/si-runs.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=a66ace282fa04e420c6744601d0a299d)

## Turn it on

1. Open your workspace and click **Self-improvement** in the **Monitoring** section of the sidebar.
2. Switch the toggle at the top right to **Active**. It shows when the next run starts.
3. Review the **Settings** tab (below) and adjust the schedule, the chats it reviews and the budget.

While it's switched off, scheduled runs don't start, but runs that already started can still be opened, applied, dismissed or stopped.

> [!NOTE]
>
> Self-improvement settings and runs need workspace admin access. Settings are saved as you change them; they aren't part of a workspace version.

## Settings

The **Settings** tab has four sections.

### 1. Run configuration

Choose when a run starts and which chats it reviews.

* **Frequency**: **Daily** or **Weekly**, with the **Day**, **Time** and **Time zone**. A daily run reviews the previous 24 hours of chats; a weekly run reviews the previous week. A run starts within an hour of the time you choose, and the page tells you roughly when.
* **Review chats matching All / Any of these conditions**: narrow the chats it looks at. Each condition checks **Sessions** (whole conversations) or **Traces** (individual answers) against a subset of the filters in [Chat History](https://docs.upsolve.ai/ai-agent-builder/chat-history.md), for example *Errors is more than 3*, or only chats with negative feedback. Eval filters aren't available here. You can add up to 10.
* **How to review the chats that match** (optional, per condition): extra instructions for those chats, such as "find which table or column the error came from, and fix the skill or prompt that led the agent there."

![Run configuration settings with a weekly schedule on Thursday at 01:45 Europe/London, and a condition reviewing sessions with more than 3 errors](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/si-settings-schedule.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=596d87831e80831f9af8d5b2d622a3f7)

Two rules keep runs focused and cheap:

* **A chat is never reviewed twice.** Once a run has read a chat, later runs skip it, whether you applied that run or dismissed it.
* **Only chats answered by the live version count.** Playground chats and chats from older versions are skipped, so a run never "fixes" something you've already changed.

### 2. Result

What happens to the changes a run makes. Today that is **Suggest changes for my review**: changes wait with the run until you apply them to your draft or dismiss them. A run always works on a copy of production; your draft and production are untouched until you decide.

### 3. Budget

One monthly spending limit, in US dollars, covering every run in this workspace, scheduled or manual. Pick a preset ($5, $10, $25, $50), type your own, or choose **No limit**. The default is \$10.

A run that would go past the limit doesn't start, and unused budget doesn't roll over. Your organization's AI credit balance applies either way.

![Budget section showing \$2.42 spent of a \$5.00 monthly limit with the next reset date, and the Instructions section with the platform-default prompt](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/si-settings-budget.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=ca669b33d8d16441e521ec004bb483bf)

### 4. Instructions

The complete prompt the Builder agent follows on every run: what to look for (errors, wrong answers, thumbs-downs, low-confidence answers, slow answers where the agent searched or guessed), how to fix the cause rather than the single question, and how to report back. Edit it freely, for example to tell it what matters most in your business. **Reset to default** restores Upsolve's version.

The safety rules (never saving a version, never changing row-level security or the schema) are enforced by the platform, not by this text, so editing the instructions can't remove them.

## What a run does

Every run follows the same four steps, shown as progress on the run:

1. **Copied production.** The run takes a copy of the version your users are on. Your draft is set aside and restored afterwards exactly as it was.
2. **Picked the chats.** It selects up to 20 chats from the period that match your conditions and haven't been reviewed before. Chats with errors or a thumbs-down come first, then the newest. If there are none, the run ends as **Nothing to do** and costs nothing.
3. **Agent reviewed and edited.** The Builder agent reads the chats, finds the causes, and edits the copy. It can change **skills**, **system prompts**, **knowledge base** files and **metrics**, and it can **add** test cases. The data model and row-level security are read-only to it. To check its work, it can run your [test cases](https://docs.upsolve.ai/ai-agent-builder/tests.md) against the copy (up to twice per run).
4. **Wrapped up.** It writes a report and a list of to-dos for you, and saves its changes with the run.

A run never publishes anything and never changes production.

## Review a run

The **Runs** tab opens with an overview: how many runs **Need review**, are **In progress**, were **Suggested** and **Applied**, how much of the budget is **Used**, and when the **Next run** is. Filter the list by status, and click a run to open it.

![A run's detail showing its trigger, start time, duration, cost, chats read and version, the four completed progress steps, and the Report tab explaining what it found and changed](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/si-run-report.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=399f53e3e8dec8a45694bea0c515cfb2)

A run's detail has five tabs:

* **Report**: what it found, what it changed and why, and what it checked and decided not to change.
* **To-dos**: things only you can do, such as fixing the data, adding a table to the data model, or confirming a business rule the agent shouldn't guess.
* **Changes**: every change, marked added, modified or removed, with the **Before** and **After** of each.
* **Chats**: the conversations it read.
* **Activity**: the run's step-by-step log, including any test results.

![The Changes tab showing a modified skill with its before and after content](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/si-run-changes.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=9704fc0a5b2f278c45fa96a03ac5f75a)

Then decide:

* **Apply to my draft**: the run's changes are merged into your draft. Where you have changed the same thing differently since the run started, **your version is kept** and the difference is shown as a conflict for you to resolve. Applying doesn't publish anything: review the draft, run your tests, and save a version as usual.
* **Dismiss**: throw the changes away. The chats it read stay marked as reviewed.
* **Stop**: cancel a run that's still in progress. Your draft is restored.

The sidebar shows how many runs need review, so you'll see when a new one is waiting.

## Run it now

**Run now** starts a run immediately. It reviews the last 24 hours of chats and ignores your chat conditions, which makes it a quick way to see what Self-improvement would do before you rely on the schedule. Manual runs count towards the monthly budget.

## Status reference

| Status | Meaning |
| - | - |
| **Queued** / **Running** / **Finishing** | The run is in progress. |
| **Needs review** | The run suggested changes and is waiting for you. |
| **Applied** | You applied its changes to your draft. |
| **Dismissed** | You dismissed its changes. |
| **Nothing to do** | No chats to review, or nothing worth changing. |
| **Failed** / **Stopped** | The run didn't finish. Your draft was restored. |

## Who a run acts as

A run acts as the person who switched Self-improvement on, while they are still an owner or admin. Otherwise it acts as the longest-standing owner, then admin. A run can take up to 30 minutes.

## Next steps

> **[Builder Agent](https://docs.upsolve.ai/ai-agent-builder/builder-agent.md)**
>
> The agent that does the work, available to chat with any time.

> **[Tests](https://docs.upsolve.ai/ai-agent-builder/tests.md)**
>
> The checks each run makes against its own changes.

> **[Chat History](https://docs.upsolve.ai/ai-agent-builder/chat-history.md)**
>
> The conversations, evals and feedback a run reviews.

> **[Skills](https://docs.upsolve.ai/ai-agent-builder/skills.md)**
>
> The context runs most often improve.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.