The Workspace Agent

A workspace has two agents, and they never swap jobs:

​

What is the Workspace Agent?

Every workspace contains one agent — an AI analyst that:

• Converts natural language questions into SQL
• Analyzes results and provides insights
• Creates visualizations from query results
• Learns from examples (Golden Assets)

The agent has no separate lifecycle. Where you previously created an agent and linked it to a data model version, a workspace is that pairing: the schema on its Data Model page and the context you encode around it are versioned, saved and promoted together.

​

Where the Agent’s Context Lives

Each piece of the agent’s context is a page in the workspace sidebar, under Context: Golden assets are worked examples it retrieves for similar questions. They’re test cases with Use as golden asset switched on, so you manage them on the Tests page. Work through them in the order the sidebar lists them — the schema first, because nothing below it can be written without knowing which tables exist. See Encode Your Context for how to decide where a piece of business knowledge belongs.

​

Testing in the Playground

The Playground is where you chat with the workspace’s agent on any version, as yourself or as one of your project users:

• Pick a project user with the Chatting as picker — the conversation runs under that user’s row-level security, exactly as an embedded chat would
• Open the Observability panel: its Context tab shows the data model, knowledge base and skills the version carries, and its Trace tab shows each answer’s tool calls and SQL

Conversations where you preview another user’s access are kept out of that user’s chat history. See Playground for the full guide.

​

Versioning and Production

You don’t version the agent on its own. The workspace version bar — above every page — tracks the whole workspace:

1. Edit any page; changes autosave to the draft
2. Click Save version to freeze the draft as a new version, capturing the schema, prompts, skills and assets together
3. Promote to production — this is what deployed users and embeds are served

Because the schema and the agent ship together, the old failure mode of an agent pointing at a stale data model version is gone by construction. See Workspaces for the full lifecycle.

​

Deploying the Agent

The workspace’s Deploy page has everything for putting the agent in your product: a setup prompt for a coding assistant, the ids, the backend call and the iframe (/share/workspace/{projectId}/{workspaceId}?jwt=<token>), and a preview link generator that mints a real one-hour project-user token. See Workspaces → Deploying a Workspace and Embed Upsolve in your product.

​

Admin View vs User View

​

Admin View

As a builder in the Playground, you see full details:

• Every tool call the AI makes
• SQL queries generated
• Step-by-step reasoning via the observability trace
• Token usage and timing

​

User View

End users see a clean interface:

• Just the question and answer
• Charts and insights
• No technical details

Preview it yourself by chatting as a project user in the Playground, or by opening a generated preview link from the Deploy page.

​

Best Practices

​

1. Start with Golden Assets

Add 10-20 golden assets covering common questions before going live.

​

2. Use Descriptive Data Models

Column descriptions on the Data Model page help the agent understand your schema.

​

3. Run Evals Regularly

Create a test suite and run it whenever you update the workspace.

​

4. Monitor in Chat History

Periodically check Chat History to see how the agent handles real questions, and Agent Observability for the traces behind them.

​

Next Steps

• Encode Your Context — the map of where business knowledge belongs
• Follow the Complete Setup Guide from project to production
• Build canvases to give every customer dashboards with their own data