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

> The Builder agent sets up a new workspace for you, then writes the context your analytics agent works from whenever you describe a change: 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.

You meet it in two places:

* **When you create a workspace**, it offers to [set the whole workspace up](#set-up-a-new-workspace) from your schema, your files and your brand, in a few minutes.
* **Afterwards**, as a chat on the workspace's Home page, where you ask for one change at a time.

![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/b1jyK_S-fI8SzClk/images/ai-agent-builder/improve/builder-empty.png?fit=max\&auto=format\&n=b1jyK_S-fI8SzClk\&q=85\&s=956a93ca5e4456a6d65503c89e23f722)

## Set up a new workspace

Every new workspace opens on guided setup, where the Builder agent (shown as **Dash Builder** on these screens) offers to configure it for you. Click **Start**, answer a few optional questions, and watch it work. Or click **I'll configure it myself** to skip it.

![Workspace preparation, step Start: Dash Builder can set this workspace up for you, listing what it reads and what it writes](https://mintcdn.com/upsolve/iEwehldJC3a_PbxW/images/ai-agent-builder/setup/setup-start.png?fit=max\&auto=format\&n=iEwehldJC3a_PbxW\&q=85\&s=96c4808567c85af649985c00e43b99f9)

> [card] What it reads
>
> Your schema, and what your core tables actually contain. The MCP servers you pick, such as a data catalog. Files you upload, such as metric definitions or naming notes. Your website, logo and a few words on your brand.

> [card] What it writes
>
> Table and column descriptions. Tables switched off that aren't for analysis. Knowledge base files. Two or three starter skills. The agent's system prompts. A theme from your brand.

It goes through these steps:

1. **Start**: see what it will read and write.
2. **Connectors**: pick the MCP servers it should take your team's definitions from. For a workspace on your API, add your docs URL.
3. **Files**: upload documents it should read first.
4. **Design**: give it your website, logo and the look you want, or skip to keep the default theme.
5. **Set up**: choose whether it asks before each read-only query (**Ask me each time**) or runs them unattended (**Run queries automatically**), then watch it work. You can stop it at any point.
6. **Done**: review what it wrote, with links to the Data Model, Knowledge Base and Customize pages.

![The setup progress feed: skills and prompts written, the theme designed, and read-only checks of real values in the data](https://mintcdn.com/upsolve/iEwehldJC3a_PbxW/images/ai-agent-builder/setup/setup-running.png?fit=max\&auto=format\&n=iEwehldJC3a_PbxW\&q=85\&s=7455c6a83414ae8fcbc2aedc90d86295)

A few rules keep its first pass honest:

* **Your words win.** Where your files or a connected system say what something means, it writes it their way, not from the column name.
* **It checks before it describes.** It queries your core tables to see real status codes, categories and date ranges, rather than guessing from names. Organizations that handle confidential data are never queried, so there it works from names, types and your files.
* **It labels guesses.** A metric definition it inferred rather than found goes in a knowledge base file marked as an assumption, so you can confirm or correct it.
* **Connected systems are data, not instructions.** If a document or tool result from a connector tries to tell it what to do, it ignores the request and writes a note telling you which connector sent it.

On a procurement database it wrote, in about ten minutes: column descriptions for the core tables, three knowledge base files (one marked "inferred" for the builder to confirm), three skills, the agent's prompts and a theme.

![What was written: three context files including On-Time Delivery Definition (inferred), three skills, agent instructions, a theme, and the other changes, based on 9 read-only queries](https://mintcdn.com/upsolve/b1jyK_S-fI8SzClk/images/ai-agent-builder/setup/setup-done-written.png?fit=max\&auto=format\&n=b1jyK_S-fI8SzClk\&q=85\&s=c861121d83873da57b40bdc7f0b9cb3a)

For a workspace with **no database**, it reads your API's endpoints and the docs page you gave it, and writes skills that use real operations, instructions on acting safely, knowledge base files from your docs, and example questions to try first.

When a run completes, the setup is saved as a version called **Set up by Dash Builder** and promoted to production, so the workspace can answer straight away. If production requires tests, the version is saved but you deploy it yourself, which runs them. A run that was stopped or failed stays a draft for you to review and save. Guided setup doesn't add data security rules: add them before you sign customers in. See [Complete Setup Guide](https://docs.upsolve.ai/ai-agent-builder/setup-guide.md#step-4-set-up-the-workspace) for the whole flow.

## 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 in a chat: ship. The Builder agent has no way to save a version or promote one to production. That is your decision. The one exception is [guided setup](#set-up-a-new-workspace), which you start yourself: when it completes, Upsolve saves and promotes what it wrote.

> [!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, versions and production](https://docs.upsolve.ai/ai-agent-builder/workspaces.md#draft-versions-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 draft 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/b1jyK_S-fI8SzClk/images/ai-agent-builder/improve/builder-approval-mode.png?fit=max\&auto=format\&n=b1jyK_S-fI8SzClk\&q=85\&s=423102fceb308c7cdea28d47b4abca4a)

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/b1jyK_S-fI8SzClk/images/ai-agent-builder/improve/builder-diagnosis.png?fit=max\&auto=format\&n=b1jyK_S-fI8SzClk\&q=85\&s=6bf36713889895967d928dff580b1457)

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/b1jyK_S-fI8SzClk/images/ai-agent-builder/improve/builder-fix-from-tests.png?fit=max\&auto=format\&n=b1jyK_S-fI8SzClk\&q=85\&s=f908edde50d6ba98c5eab8407125f6df)

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

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

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

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

> [card] [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.