Complete Setup Guide

End-to-end walkthrough from a blank project to a production-ready workspace.

This guide walks you through the complete process of setting up Agent Studio from scratch — from connecting your database to deploying a live workspace your users can chat with.

The full journey

Here’s every step from nothing to production:

Agent and application setup can happen in parallel once your workspace is publishing cleanly. Organizations and users come last — they’re what gates live access.

Step 1: Create your project

A project is the container for everything: your connections, workspaces, and the organizations and users who will access them.

1. Go to the Projects section
2. Click Create Project
3. Enter a name (e.g., “Customer Analytics”)
4. Click Create

When the project is created, Upsolve automatically sets up default user roles and an admin user for you.

Step 2: Add a connection

Connections link your project to a database. Every workspace in the project is created over one.

1. Open Project settings → Connections in your new project and select your data source from the Connect data cards
2. Choose Try Demo Data to explore with sample data, or connect your real database
3. For real databases, select your database type, enter credentials, and test the connection
4. Click Save

Step 3: Create your workspace

A workspace is one data model and one agent, versioned and published together. Creating it introspects the connection so the schema is ready to curate.

1. On your project page, click New workspace
2. Enter a name and select your connection
3. Click Create workspace

A workspace’s connection is required and cannot be added later — the workspace’s schema is read from it.

From there, configure the data model on the workspace’s Data Model page:

1. Select tables — Uncheck tables that aren’t relevant to this agent’s use case
2. Select columns — Uncheck 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 enumerate valid filter values at query time

See The Workspace Data Model and Data Model & Schema for a full guide on what makes a good data model configuration.

Configure data security

If you’re building for multiple customers or need to restrict what data each user sees, configure row-level security rules on your tables now.

1. On the Data Model page, click on a table
2. Go to its Data Security tab
3. Write a filter rule using {{organization.*}} or {{user.*}} placeholders:
   SELECT *
   FROM "orders"
   WHERE "company_id" = {{organization.company_id}}
   
4. Changes autosave to the workspace draft

See Row-Level Security for the full guide on security rule types, testing, and global rules.

Step 4: Encode your context

This is the core work that determines agent quality. Work through the workspace’s context pages — start with the two essentials, then layer on the rest as needed:

System Prompts — Write the business rules, KPI definitions, and behavioral guardrails the agent should always follow. See System Prompts.

Assets — Add 10–20 examples covering your highest-frequency question patterns. Golden Queries pair a natural language question with the correct SQL; Golden Charts go further and include a chart configuration too. The agent retrieves these as reference when answering similar questions. See Golden Assets.

Beyond those essentials, the workspace offers more context pages you can adopt as your agent matures:

• Skills — reusable procedures and conventions the agent loads on demand (Beta)
• Knowledge Base — markdown reference documents (definitions, policies, caveats) searched at chat time
• Memory — per-end-user preference recording, applied automatically in future conversations (Beta)
• MCP as Context Source — live context from external tools and systems

Step 5: Test in the Playground

Before shipping, chat with the agent in the workspace’s Playground as one of your project users:

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 charts
3. Open the Observability panel on a few responses to confirm the logic is correct

Step 6: Publish and go to production

The workspace version bar sits above every page:

1. Review the draft — changes autosave as you work
2. Click Publish to stage a new workspace version
3. Promote it to production — deployed users and embeds are served the production version

See Workspaces → Draft, Publish and Production for the full lifecycle.

Step 7: Create an application

Applications hold the dashboard side of your product — templates your customers get private copies of.

1. Go to the Applications section
2. Click Create Application
3. Enter a name and select the workspace’s data model
4. Click Create

Then build templates:

1. Click Add Dashboard in your application
2. Name it and add charts by clicking Add Chart
3. Configure each chart with your data and arrange the layout
4. Click Save

When your templates are ready, preview each as a test user to confirm RLS is working, then click Publish on each template — this propagates copies to all spaces.

Step 8: Sign your users in

Your customers become project organizations and their people project users, carrying the properties your security rules read. You don’t register them ahead of time: your backend makes one call per sign-in, POST /v1/api/projects/embed-token, which creates the organization and the user the first time, keeps their properties current after that, and returns the token your iframe needs.

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": "[e-mail]", "properties": { "department": "sales" } }
  }'

The workspace’s Deploy page has every id this needs, a link to create the API key, and a setup prompt that does the whole integration through a coding assistant. The full walkthrough is Embed Upsolve in your product.

To try security rules before any of that exists, add a test organization and user by hand in the project’s Organizations and Users tabs, with the same properties, and preview the workspace as them from its Deploy page.

You’re done!

Users can now:

• Chat with the workspace’s agent using natural language
• View dashboards with their filtered data
• Create their own charts and dashboards in their space

Setup checklist

Step	Required for
Project created	Everything
Connection added	Data access
Workspace created	Everything agent-side
Data model curated (tables, columns, descriptions)	Agent accuracy
Data security configured	Multi-tenant isolation
Context encoded (prompts, Assets, skills, knowledge base, memory)	Agent accuracy
Workspace published and promoted to production	User access to agent
Application created	Dashboard features (embeddable)
Dashboard templates published	User access to dashboards
Backend calls embed-token on each sign-in	End-user access and tenant isolation

Next steps

Encode Your Context

Deep dive into all context entry points: data model, system prompts, Assets, skills, knowledge base, memory, and MCP.

Deploy & Expose

Embed the workspace in your product: one API key, one backend call, one iframe.