Skip to main content

​
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)
A workspace's Playground: chatting as a project user, with the observability panel showing the agent's data model, knowledge base, skills and 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, published 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: 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 as one of your project users, before anything is deployed:
  • 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 to see the trace of every answer: schema retrieval, golden assets used, SQL generated, charts built
  • The context panel shows the data model, knowledge base, skills and assets this agent is currently carrying
Conversations here are kept out of end users’ chat history.

​
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 Publish to stage 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 produces the embed snippet and preview links for putting the agent in your product:
  • An iframe pointed at /share/workspace/{projectId}/{workspaceId}?jwt=<projectUserToken>
  • A preview link generator that mints a real one-hour project-user token
  • A status strip saying which version the embed serves
See Workspaces → Deploying a Workspace and the Deploy & Expose guides.

​
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