Complete Setup Guide

• Let the Builder agent set it up. When you create a workspace, the Builder agent offers to configure it for you. It reads your schema, looks at what your core tables contain, and writes descriptions, skills, prompts, knowledge and a theme in a few minutes, while you watch.
• Configure it yourself. Curate the data model and write each piece of context on the workspace’s own pages.

​

The full journey

​

Step 1: Create your project

1. Go to Projects.
2. Click Create Project.
3. Enter a name (for example, “Customer Analytics”). To explore first, switch on Set up complete sample project for a project that comes with sample data, a workspace and charts.
4. Click Create Project.

​

Step 2: Connect your data or your API

• Your product’s API. Point Upsolve at your OpenAPI spec, and the agent can look things up and act in your product. See Connect your API.
• Easy connect. Sign in to the tools your team uses (HubSpot, Salesforce, Stripe and more). Upsolve syncs and hosts the data for you.
• Self connect. Bring your own database or warehouse: Postgres, Snowflake, BigQuery, ClickHouse and more. Enter credentials, test the connection and save. Your data stays where it is. See Projects & Connections.
• Upload a CSV of up to 5 MB, or Try with Sample Data to explore before you connect anything real.

​

Step 3: Create your workspace

1. On your project page, click New workspace.
2. Enter a name, and optionally say what the workspace is for.
3. Choose a connection. Choose No database for a workspace that answers through your APIs and MCP servers instead of SQL. You can give it a database later in Workspace settings → Connection.
4. Click Create.

​

Step 4: Set up the workspace

​

Option A: Let the Builder agent set it up

• Ask me each time: the run pauses and shows you every query before it runs. Slower, because it waits for you.
• Run queries automatically: the run works unattended and never stops to ask.

• Investigates your two or three core tables with read-only queries, to see what their key columns actually contain.
• Writes table and column descriptions in your schema’s own words, including what codes and status values stand for.
• Switches off tables that plainly aren’t for analysis, such as migration bookkeeping or test copies. It leaves a table on when it isn’t sure.
• Writes knowledge base files for what the schema can’t express: how a metric is computed, which statuses count as live. Anything it inferred rather than found in the data is labelled as an assumption, so you can check it.
• Creates two or three starter skills for the questions the schema clearly supports.
• Writes the agent’s system prompts: your domain, its vocabulary, and the rules an analyst would take for granted.
• Designs the theme from your brand, if you gave it one.
• May add starter test cases for the questions it’s confident about.

• If production requires tests, the version is saved but not promoted. Deploy it to production from Deploy to…, which runs the tests.
• If the run was stopped, failed, or hit its step or cost limit, it stays a draft for you to review and save yourself.

​

Option B: Configure it yourself

1. Select tables: switch off tables that aren’t relevant to this agent’s use case.
2. Select columns: switch off sensitive or irrelevant columns within each table.
3. Add descriptions: annotate tables and columns with plain-English context, so the agent understands what the data means, not just what it’s named.
4. Mark selectables: flag categorical columns (region, status, owner) so the agent can look up their valid values when it answers.

• System Prompts: the business rules, KPI definitions and guardrails the agent should always follow.
• Golden Assets: 10–20 worked examples covering your most common questions, each a question with the correct SQL and, optionally, a chart. They’re test cases with Use as golden asset switched on, so one example both teaches the agent and checks it. The agent looks them up when it answers similar questions.

• Skills: reusable procedures and conventions the agent loads when a question needs them.
• Knowledge Base: reference documents (definitions, policies, caveats) searched at chat time.
• Memory: preferences each end user expresses, applied in their later conversations.
• MCP as Context Source: live context from your other tools and systems.

​

Configure data security

1. On the Data Model page, open the Global Data Security tab beside Tables to write rules that apply to every table with a matching column. To give one table its own rule, select it and open its Data Security tab.
2. Write a filter that uses {{organization.*}} or {{user.*}} properties:
   SELECT *
   FROM "orders"
   WHERE "company_id" = {{organization.company_id}}
   
3. Changes save to the workspace draft as you go.

​

Step 5: Test in the Playground

1. Pick a user with the Chatting as picker. The conversation runs under that user’s security rules.
2. Ask your most common questions, and check the SQL and the charts.
3. Open the Observability panel on a few answers to check the agent’s reasoning.

​

Step 6: Save a version and go to production

1. Review the draft. Changes save to it as you work.
2. Click Save version to freeze the draft as a new version.
3. Promote it to production. Your users, embeds and connectors are served the production version.

​

Step 7: Build canvases for your customers

1. On the workspace’s Home, ask the agent the questions your dashboard should answer, and save each chart you want to keep to Favorites.
2. Open Canvas, create a canvas and add those charts to it.
3. Save a version of the canvas, then open the share dialog and turn on Workspace.
4. Click the rocket beside the version picker to promote that version.

​

Step 8: Sign your users in

curl https://api.upsolve.ai/v1/api/projects/embed-token \
  -H "Authorization: Bearer $UPSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "YOUR_UPSOLVE_ORGANIZATION_ID",
    "projectId": "YOUR_PROJECT_ID",
    "organization": { "externalId": "acme", "name": "Acme Corp", "properties": { "company_id": "acme-123" } },
    "user": { "externalId": "user-42", "name": "john@acme.com", "properties": { "department": "sales" } }
  }'

​

Other ways to reach your users

• From Claude and other AI assistants, through the Upsolve MCP server.
• In Slack, where your team asks the agent in a channel or a DM. See Use Upsolve in Slack.

​

You’re done

• Ask the workspace’s agent questions in plain language, and get answers and charts drawn from their own data.
• Open the canvases you shared with the workspace.
• Save charts to their favorites and build canvases of their own.

​

Setup checklist

​

Next steps