> ## 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.

# Builder Agent

> Describe the change you want in plain English, and the Builder agent writes the context your analytics agent works from: schema descriptions, skills, prompts, knowledge and tests.

> [!NOTE]
>
> The Builder agent (also called the **AI Builder**) is a **Beta** feature.

Your workspace's analytics agent is only as good as the context behind it: column descriptions, business definitions, skills, system prompts and test cases. The Builder agent writes that context for you. Describe what you want ("explain what `spend_against_contract` means", "why did this answer get the wrong supplier count?") and it reads the workspace, checks your data, and makes the edit.

It is a second agent, separate from the analytics agent your users talk to. The analytics agent answers questions about your data. The Builder agent changes how the analytics agent works.

![The workspace Home page in Builder mode, showing 'Build by describing it', a message box with a Manual approval selector, and four suggested prompts](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/builder-empty.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=f9a8cf0ffc7615e99f00b6e2f6bba948)

## Open the Builder agent

1. Open your workspace and click **Home**, the first item in the sidebar.
2. In the toolbar at the top, switch from **User** to **Builder**.

**User** mode chats with the workspace as yourself, the way your end users do. **Builder** mode opens the Builder agent. Each Builder conversation gets its own address, and the conversation menu at the top left lists **Your chats** so you can return to earlier work or start a **New chat**.

You can also open it from anywhere in the workspace with the floating **Need help with this workspace?** tab in the bottom-right corner.

On a new chat, four suggested prompts get you started. Clicking one fills in the message box without sending it, so you can edit it first:

* **Describe my tables**: write table and column descriptions from your schema and real values.
* **Define a business term**: turn a term your team uses into a definition the agent can apply.
* **Diagnose a bad answer**: work out why the analytics agent got something wrong, and fix the context that led it there.
* **Review my unsaved changes**: summarize what is in the draft before you save a version.

> [!NOTE]
>
> Only builders (owners, admins and members) see the **Builder** switch. Read-only members and end users never do.

## What the Builder agent can do

The Builder agent works on one workspace at a time. It can:

| Area | What it can do |
| - | - |
| **Data model** | Read tables and columns, write and edit table and column descriptions, turn tables on or off, make bulk edits, and show the draft's diff. |
| **Row-level security** | Read, preview, create, update and remove RLS rules, and set per-table overrides. |
| **Your data** | Run **read-only** SQL against your database, for example to see real values before describing a column or to check a number the agent got wrong. |
| **Skills** | List, read, create, update and remove [skills](https://docs.upsolve.ai/ai-agent-builder/skills.md). |
| **System prompts** | Read and update the [system prompts](https://docs.upsolve.ai/ai-agent-builder/system-prompts.md). |
| **Knowledge base** | Create, edit, remove, restore and tag [knowledge base](https://docs.upsolve.ai/ai-agent-builder/knowledge-base.md) files, and read the files of a past version. |
| **Tests** | Create, edit and remove [test cases](https://docs.upsolve.ai/ai-agent-builder/tests.md), and read past test runs and their results. |
| **Chat history** | Read the workspace's conversations, sessions and traces, so it can find where the analytics agent went wrong. |
| **Theme** | Read, update and preview the workspace theme. |
| **Versions and connectors** | Read saved versions and the workspace's MCP and API connectors (read-only). |

It also reads the Upsolve documentation when it needs to, and ends a turn with suggested next steps you can click.

There is one thing it **never** does: publish. The Builder agent has no way to save a version or promote one to production. That is always your decision.

> [!NOTE]
>
> Running SQL is turned off for organizations that handle confidential data, and you'll see a banner saying so. In a workspace with no database, the SQL and table tools aren't available either.

## Every change goes to the draft

The Builder agent edits the workspace's **Draft** (its working copy), never a saved version. Your users keep getting answers from the version in production until you save a new version and promote it. See [Workspaces: Draft, Publish and Production](https://docs.upsolve.ai/ai-agent-builder/workspaces.md#draft-publish-and-production).

To try its changes, open the Playground and select **Draft**. **User** mode on Home uses the version deployed to the selected environment, so it won't show unpublished changes when a version is deployed. You can throw draft changes away with **Reset** if you don't like them.

### Choose how much it asks first

The selector next to the send button controls whether the Builder agent asks before it acts:

* **Manual** (the default): it asks you to approve every change before applying it.
* **Auto**: it applies draft changes and runs read-only queries without asking.

![The approval mode menu showing Manual (approve every change before it is applied) and Auto (apply draft changes and run queries without asking)](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/builder-approval-mode.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=dd762cc5fb62d1abff8152dac4df8be3)

In Manual mode, each proposed change appears as a card in the conversation, labelled **Needs your approval**. A card for a draft change says it goes to the draft. A card for a query says it runs against your live database and changes nothing in the workspace. On each card you can:

* **Approve**: apply this change (or run this query).
* **Decline**: skip it. You can add a reason, and the Builder agent reads it on its next turn.
* **Always allow**: approve it and switch to Auto for the rest of the conversation.

The approval mode is remembered in your browser. It is a personal preference, not an organization policy: either way, nothing reaches your users until a version is saved.

## Improve the agent from its chat history

The most useful thing to give the Builder agent is evidence. It can read the workspace's [Chat History](https://docs.upsolve.ai/ai-agent-builder/chat-history.md), so you can point it at real conversations and ask it to fix what went wrong:

* "Look at this week's chats with a thumbs-down and tell me what they have in common."
* "The agent keeps grouping small suppliers into 'Other'. Find the chats where it did that and stop it."
* "Here's a trace ID where the answer was wrong. What caused it?"

The Builder agent traces a bad answer back to the context that caused it (a missing column description, a skill pointing at the wrong table, an undefined business term), fixes that context, and tells you what it changed and why.

![A Builder conversation where the agent explains what went wrong in two failing answers and traces both to a skill that pointed at tables that don't exist](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/builder-diagnosis.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=87df035bec8f731f14fcfbc34875244e)

It also tells you what it chose **not** to change, and flags decisions that belong to you. In the conversation below it fixed a skill and two column descriptions, then asked the builder to confirm a business rule rather than guessing:

![The end of a Builder conversation listing the column descriptions it changed, a decision for the builder about cancelled purchase orders, and a note to re-run the tests](https://mintcdn.com/upsolve/6hKReQ_w6B1jt5Gu/images/ai-agent-builder/improve/builder-fix-from-tests.png?fit=max\&auto=format\&n=6hKReQ_w6B1jt5Gu\&q=85\&s=b99696cf9a011d9bc338df5cbab8d68f)

## Fix failing tests

The Builder agent can read [test runs](https://docs.upsolve.ai/ai-agent-builder/tests.md) too. After a run with failures, ask it to "fix the context based on the last test run". It reads each failing case and the evaluator's report, finds the cause, and edits the draft. Then re-run the tests to check the fix before you save a version.

You can also ask it to write test cases for you, for example "add a test case for contracts expiring in the next 90 days", once you've agreed the right answer.

## A good working loop

1. **Find the problem**: a thumbs-down in Chat History, a failing test, or a question you know the agent gets wrong.
2. **Ask the Builder agent** to diagnose it and fix the context.
3. **Review** its changes on the Data Model, Knowledge Base, Skills and Prompts pages, or ask it to "review my unsaved changes".
4. **Test**: run your test cases against the draft.
5. **Save a version** when you're happy, and promote it.

To run this loop automatically on a schedule, turn on [Self-improvement](https://docs.upsolve.ai/ai-agent-builder/self-improvement.md).

## Credits and limits

* The Builder agent runs on Upsolve's most capable model tier, and every turn uses **AI credits**. You need at least one credit remaining to start a turn.
* One turn can take up to 40 steps. Long jobs (describing a hundred columns, say) may need a follow-up "keep going".

## Next steps

> **[Tests](https://docs.upsolve.ai/ai-agent-builder/tests.md)**
>
> Write test cases and check every change against them.

> **[Self-improvement](https://docs.upsolve.ai/ai-agent-builder/self-improvement.md)**
>
> Let the Builder agent review chats on a schedule and suggest fixes.

> **[Chat History](https://docs.upsolve.ai/ai-agent-builder/chat-history.md)**
>
> Find the conversations worth improving.

> **[Encode Your Context](https://docs.upsolve.ai/ai-agent-builder/encode-your-context.md)**
>
> How each kind of context shapes the agent's answers.


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