Builder Agent

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.

​

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.

​

What the Builder agent can do

The Builder agent works on one workspace at a time. It can: 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.

​

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

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, 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. 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:

​

Fix failing tests

The Builder agent can read test runs 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.

​

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