AI Agents — Dashboard Builder

Audience: End users who can manage dashboards, Dashboard Creators, administrators, and developers. Use this document when: You want the Dashboard Builder agent to create a dashboard draft from a description, reuse a seeded sample dashboard, or explain why a dashboard draft was proposed. Canonical for: The Dashboard Builder agent, its page contexts, tools, permissions, draft workflow, and constraints. Related: AI Agents Index, End User Guide, Administrator Guide, Report Design Recommendations.

The Dashboard Builder is a built-in AI agent that turns a short description into a draft dashboard for the current module. It reuses seeded sample dashboards and the existing wireframe system instead of inventing a layout.

The Dashboard Builder creates drafts only. It never publishes, edits, archives, or deletes an existing dashboard.

Where it appears

Page	Page key	What the agent can use
All dashboards	`dashboard_index`	Accessible dashboard report sources across accessible modules.
Module dashboard list	`dashboard_module_list`	Sources in the current module only.
Dashboard detail	`dashboard_detail`	Sources in the current module only, plus the current dashboard code for context.

The page assistant uses the built-in agent code dashboard_builder. The page context supplies the module and the available sample dashboards.

Because the Dashboard Builder is a published, non-contextual agent, it can also be selected in the AI Workspace. Prefer the dashboard page version because the page supplies the module scope and sample context.

The launcher appears only when the user can manage dashboards. The required permission is action.enezadashboard.manage. The Dashboard Creator role includes the matching dashboard management task.

What the agent does

Reads the user's description.
Reads the seeded sample dashboards available for the module.
Picks a matching sample, or falls back to a compatible wireframe when no sample fits.
Rebinds every widget to a dashboard report source the user is allowed to use.
Returns a dashboard definition with a name, module, code, tabs, and widgets.
Validates the definition, report references, widget fields, and layout.
Proposes a Dashboard draft action for the user to apply.

A typical draft contains:

A dashboard name.
A module.
A unique dashboard code.
One or more tabs.
KPI, chart, and table widgets.
Layout, display configuration, and filter patterns reused from the sample or wireframe.
A summary with the tab count and widget count.

Using it

Open All dashboards, a module dashboard list, or a dashboard detail page.
Select Ask assistant.
Describe the dashboard in one message. You do not need to specify the module, data source, widget types, field names, tab names, or layout.
Review the proposed draft summary.
Apply the proposal.
The system creates the draft and opens the dashboard designer.
Review the draft in the designer.
Publish it manually when it is ready. The agent does not publish.

Example requests:

"Create a sales performance dashboard for this module."
"Build a dashboard with a KPI for open orders and a monthly trend chart."
"Make a stock overview with a KPI strip, a chart, and a table."
"Use the finance sample and adapt it to this module."

If the request is too vague to choose any source, the agent may ask one short question. Otherwise it should proceed with a recommended draft.

Sample dashboards

The agent prefers a seeded sample dashboard because samples already define the expected:

tab structure
widget mix
layout
display configuration
filter patterns

The sample is only a pattern. The agent rebinds each widget to a report source the user can actually access. It does not keep a sample report reference that is not available to the user.

If no sample fits, the agent tries a compatible wireframe. If no compatible wireframe exists, it reports the limitation instead of inventing an unsupported layout.

How a developer defines a dashboard data source

The Dashboard Builder does not define data sources. It only binds to dashboard data sources that already exist and that the user can access.

A dashboard data source is not a new model. It is an existing tabular report that has opted in to dashboard use:

text

Django model → tabular report class → dashboard_enabled = True → eligible source

A developer defines one by:

Creating a tabular report class over the model, using TabularReportView, SummaryReportView, or DetailedReportView.
Declaring report_model, columns, and, when needed, group_by, date_field, computations, and parameter_spec.
Setting dashboard_enabled = True.
Optionally setting dashboard_code, report_url_name, and dashboard_entity_scoped.
Ensuring the report class is imported at startup so it registers.
Granting the report output permission, in the form output.<app_label>.<report_slug>.view.
Confirming the source appears through list_dashboard_report_sources(...) or the dashboard designer.

Important rules:

Only tabular reports are dashboard data sources in v1.
Crosstab, time-series, document, and drill-down reports are not dashboard data sources in v1.
A group_by field must also be in columns to be a usable dimension.
Computation fields and numeric model fields are measures.
Dashboard configuration never grants report access. The user must already have the report output permission.

Canonical developer guide:

Tools used by the Dashboard Builder

Tool	Purpose
`dashboard_recommend_plan`	Recommend a dashboard definition from a description, optional name, module, and optional sample code.
`dashboard_list_examples`	List seeded sample dashboards available for the module.
`dashboard_get_example`	Read one full seeded sample definition.
`dashboard_get_options`	List available dashboard report sources and options for a module.
`dashboard_validate_plan`	Validate a dashboard definition and its report references.
`dashboard_propose_draft`	Create the proposed Dashboard draft action for user confirmation.
`metadata_discover_models`	Read models available to the user when the agent needs context.
`metadata_get_model_schema`	Read model fields and policies when the agent needs context.

The agent calls dashboard_recommend_plan first. It calls dashboard_propose_draft with the returned definition. It uses dashboard_get_options or dashboard_validate_plan only when the recommendation fails or the user asks for a specific change.

Draft and publish rules

Rule	Meaning
Draft only	The proposed action creates a dashboard draft. The definition is normalized with publishing disabled.
Preview before publish	The draft opens in the designer. A human reviews and publishes it.
No existing edits	The Dashboard Builder does not edit, archive, or delete an existing dashboard.
No publishing	The agent cannot publish.
No new sources	The agent cannot create report sources, Python modules, or Python scripts.
Module scope	On a module page, the draft must stay in that module. It cannot reference another module's sources.

Applying the proposal creates the dashboard under the current module with a unique code. The action records the result and opens the designer for the new draft.

Permissions and data scope

The Dashboard Builder requires:

action.enezadashboard.manage.
Access to the current module.
Access to each dashboard report source it binds.
The output permission for each report source used by a widget.

The agent never uses a data source the user cannot access. If no dashboard report source is available for the selected module, it reports that no source is available rather than inventing one.

On the All dashboards page, the agent may use sources from more than one accessible module. On a module dashboard page, it is restricted to that module.

Administrator notes

The Dashboard Builder is a built-in agent:

Property	Value
Agent code	`dashboard_builder`
Name	Dashboard Builder
Application	`enezadashboard`
Module	`dashboard`
Required permission	`action.enezadashboard.manage`
Contextual	No
Built-in	Yes
Default	No

ai_seed_tools ensures the agent exists and keeps its built-in instructions and tools synchronized. ensure_builder_agents() also ensures it when the AI Workspace loads.

Because the built-in instructions and tools are synchronized from code, local edits to the built-in Dashboard Builder can be overwritten by a later ai_seed_tools run or agent synchronization. Treat the built-in instructions as code-managed.

The agent's tools are part of the built-in tool catalogue. Run:

bash

python manage.py ai_seed_tools

after deploying changes to the dashboard builder or its tools.

Troubleshooting

Problem	What to check
No Ask assistant button on a dashboard page	The user lacks `action.enezadashboard.manage`, the module is not accessible, or the page is not a dashboard page.
"No dashboard report data sources are available"	The module has no accessible dashboard report sources, or the user lacks the matching output permission.
"No seeded sample dashboards are available"	No seeded samples exist for the module. The agent may still use a wireframe; if none is compatible, it reports the limitation.
The draft is not visible to other users	A draft is not published. Publish it in the designer to make it live.
Validation errors	The recommended source, widget field, layout, or report reference is invalid. Ask the agent to revise the plan.
The agent asks a question	The description was too vague to choose any source. Add the module, the metric, or the comparison you need.
Applying the proposal fails	The user may have lost dashboard or module permission, or a source may have become unavailable. Recheck access and regenerate the plan.
The code already exists	The system generates a unique code for the module. Change the name if you want a different code.

Do not

Do not ask the Dashboard Builder to publish a dashboard.
Do not ask it to edit or delete an existing dashboard.
Do not expect it to create a report source, Python module, or Python script.
Do not use it to reference another module's sources from a module page.
Do not treat a draft as live until a human publishes it.
Do not bypass dashboard permissions or module access.

A note on testing

Per project rules, the developer or agent does not run or claim test results. The user is solely responsible for all testing and validation of the dashboard drafts, permissions, and publishing described in this guide.