Dashboards
Every workspace has one dashboard, and your agent builds it. Each view is a page the agent writes in HTML from a small set of live elements (numbers, charts, tables, lists), bound to named queries over the workspace database and your superagnt account's own data. People in the workspace open the views in the superagnt app, and the numbers are current every time.
What a dashboard is
A dashboard is a set of views. A view is one HTML page built from sa-* elements, each bound to a named query, so the page always shows what the data says now. A workspace has exactly one dashboard, and it shows its views in the order the agent sets.
There is no drag-and-drop builder. Agents write the dashboard: Claude, Codex or any MCP client connected to the workspace, a deployed agent with the dashboard tools turned on (dashboards_enabled in its config), or the Agnt Wizard in the superagnt app. You say what you want to see in the conversation, and the agent changes it when you say what is wrong.
In the superagnt app the views are under Dashboard in the sidebar. A view can name the deployed agent it is about, and that view then opens beside the agent's chat.
The files
Under the hood a dashboard is a small folder of text files. The agent reads and writes them through the dashboard tools; nobody sees a file or a line of SQL in the app.
| File | What it holds |
|---|---|
dashboard.json | The dashboard's title and its views in order, each with a title, a description and, optionally, the deployed agent it is about. |
views/<slug>.html | One view: a page of plain HTML and sa-* elements. |
components/<tag>.html | A piece of HTML several views reuse, placed in a view as its own tag. |
queries/<name>.sql | One named query: a read-only SELECT on the workspace database, or a platform dataset by name, with typed params that have defaults. |
-- Leads that entered each stage in the window.
-- @param days int = 30
select stage, count(*) as leads
from leads
where entered_at >= now() - make_interval(days => :days)
group by stage
order by leads desc<sa-chart label="Leads by stage" query="leads_by_stage" kind="hbar"
x-field="stage" y-fields="leads" sort="desc" format="number"></sa-chart>
<sa-table label="Every stage" query="leads_by_stage"></sa-table>How an agent builds a view
- 01
Learn the rules and the data
agnt_dashboards_guidereturns the authoring guide, andagnt_dashboards_describe_datalists the tables and platform datasets a query can read, so the agent writes against real columns instead of guessing them. - 02
Write a draft
agnt_dashboards_apply_templatestarts a view from a template, andagnt_dashboards_write_filewrites files from scratch. Every change goes into the agent's own draft, and every write comes back with its problems in plain words: the file, the line and what to change. A query runs once as it is saved and returns its columns and a few sample rows. - 03
Look at it
agnt_dashboards_previewrenders the view as a PNG with a report on each query's rows or error, so the agent fixes what it sees before anyone else does. - 04
Publish
agnt_dashboards_publishtakes a one-line summary and makes the draft the next version for everyone in the workspace. Any error refuses the publish and comes back as a list to fix.
| Tool | What it does |
|---|---|
agnt_dashboards_guide | The authoring guide: the files, the query grammar, every element and how publishing works. |
agnt_dashboards_describe_data | The tables and platform datasets a query can read, with their columns. |
agnt_dashboards_list_files | Every file, with the agent's own draft laid over the published version. |
agnt_dashboards_read_file | One file: the agent's draft copy if it changed it, else the published one. |
agnt_dashboards_write_file | Save a whole file to the draft. Returns its problems, and a query's columns and sample rows. |
agnt_dashboards_edit_file | Replace exact text in a file without resending all of it. |
agnt_dashboards_apply_template | Start a new view from a starter template. |
agnt_dashboards_preview | Render one view as a PNG with a report on each query. Read-only. |
agnt_dashboards_publish | Publish the draft as the next version, for everyone in the workspace. |
agnt_dashboards_history | The published versions, newest first, with who changed what and why. |
agnt_dashboards_restore | Put one view back to an older version, as a new version. |
agnt_dashboards_delete_file | Delete a file in the draft. It leaves the dashboard on publish. |
agnt_dashboards_discard_draft | Throw the draft away. The published version is untouched. |
agnt_dashboards_unshare_view | Turn off a view's public link at once. |
A client that lists grouped tools sees three: agnt_dashboards_read, agnt_dashboards_write and agnt_dashboards_remove, each taking the operation as its action.
The elements
A view shows data only through these 8 elements. The rest of the page is plain HTML and CSS for layout and words.
sa-valueOne number or short value with a label, an optional change and a caption.sa-meterProgress against a limit: plan limits, grant left, job progress.sa-statusA status light with a label and an optional detail line.sa-listRows of label, value and optional status.sa-sparkA sparkline for one measure over time.sa-chartA chart with up to nine series: line, area, bar, horizontal bar or funnel.sa-tableA table of rows, with an optional CSV download and approve or decline on every row.sa-actionA button from a fixed set: approve or decline a pending request.views run nothing of their own
Starter templates
A template is a working view the agent adapts. The workspace ones come with sample rows so the view renders at once; publish refuses a query that still returns them, so the agent points each one at your own tables first. The platform ones read live account data and publish as they are.
| Template | What it starts | Data |
|---|---|---|
number-row | Number row. A row of four headline numbers from one query. | sample rows |
trend | Trend. Two measures over time as an area chart, with their totals on top. | sample rows |
breakdown | Breakdown. One measure by category as ranked bars, or a funnel for ordered stages. | sample rows |
table-csv | Table with CSV. A sortable table with mixed formats and a CSV download. | sample rows |
approvals | Approvals. The requests your agents are waiting on, with approve and decline on every row. | live platform data |
credits-usage | Credits and usage. Credit balances, this month's spend, spend per day and per agent. | live platform data |
Platform data
Besides the workspace database, a query can read your superagnt account itself. A query file names a dataset with -- @source platform:<name> and holds no SQL. Reading platform data never creates a database.
| Dataset | What it holds |
|---|---|
platform:credits | Credits and spend. The data and AI credit balances, a running trial, and what this workspace spent in the window. |
platform:usage | Usage and spend. AI and data spend in the window, one row per day, hour, agent, model or data provider. |
platform:data_jobs | Data pipelines. Each data pipeline with its run and row counts, success rate, last run and queue health. |
platform:agent_runs | Agent runs. Recent runs of the workspace's deployed agents, including fires that never started. |
platform:approvals_pending | Pending approvals. The tool calls and questions agents are waiting on a person to approve or answer. |
Agent runs and pending approvals cover every agent in the workspace, so a deployed agent can preview them only with observability_enabled on. People in the workspace see them on a published view either way. Platform data never appears on a public link.
Drafts, versions and history
Each author works in a draft of its own. People keep seeing the published version until the author publishes, and two agents working on different views never block each other. While a draft is open, the dashboard shows a banner with who is building, what they asked for and the views it touches, and anyone in the workspace can discard the draft from it. There is no publish button: the agent publishes once its preview is clean.
Every publish is a version, kept with who made it and the summary they wrote. A view's change list in the app shows its versions, and any older one can be restored; agnt_dashboards_history and agnt_dashboards_restore do the same for an agent. A restore is itself a new version, so nothing is lost.
If someone published a file after the agent changed it, publish stops and names the file, so a teammate's newer copy is never overwritten by mistake. The agent reads their copy, applies its change on top and publishes again.
On every plan
The dashboard is on every plan and the same on each: up to 50 views and 100 named queries, whatever the plan. What the plans cap is the workspace database the queries read, in tables, rows and storage. Opening a view never creates a database and never starts the no-card trial's clock. An agent test-running a query on the database counts as using it, like any other query.
If the organization's trial has ended or its plan has lapsed, a dashboard tool call comes back as a requires_upgrade result with a confirm URL for a person to tap. It is a tool result, never a protocol error, so the agent can relay the offer instead of burying a failure.
The database the views read from is documented on workspace database. Canvases, and the agnt_canvas_* tools that built them, were retired for the dashboard: those tool names now answer with a pointer to the dashboard tools.