Dynamic Dashboards
Agent-defined dashboards via dashboard.yaml with 11 widget types, historical tracking, and sparkline charts — plus declared business metrics that an agent records as data and that render as tiles with no dashboard.yaml at all.
Measured against the same numbers people are
1:368 chapters
Why Every AI Agent Needs a GitHub Repo — dashboards
Apr 2026
Build and Deploy Agents in Cursor
Apr 2026

Concepts
metric, status, progress, text, markdown, table, list, link, image, divider, spacer.id and its history is drawn as a sparkline automatically.agent_dashboard_values table over time, enabling trend analysis.dashboard.yaml) showing Tasks (24h), Success Rate, Cost (24h), Health, and — while executions are in flight — Running.metrics: block of its template.yaml and records with the record_metrics MCP tool. Trinity stores each observation as a point and shows the latest value with a freshness verdict. See Declared Metrics.How It Works
The agent writes a dashboard.yaml file to its workspace.
The file defines widgets with type, title, value, and optional configuration fields.
Open the agent detail page and select the Dashboard tab to see the widgets.
Auto-refresh updates values as the agent modifies the YAML file.
Historical values are tracked automatically — sparklines appear for metrics with enough data points.
Trend indicators (↑/↓) show percentage change from previous values.
A Platform Metrics section appears at the bottom of every dashboard, showing Tasks (24h), Success Rate, Cost (24h), Health, and — while executions are in flight — Running. This section is auto-injected and not controlled by the YAML file (set platform_metrics: false at the top level to opt out).
dashboard.yaml Shape
title: "My Agent Dashboard" # required
refresh: 30 # optional auto-refresh in seconds (min 5, default 30)
sections: # required, at least one
- title: "Status"
layout: grid # grid (default) or list
columns: 3 # 1-4
widgets:
- type: metric
id: tasks_done # a stable id keeps the value's history — this is what draws the sparkline
label: "Tasks completed"
value: 42
unit: "tasks"
- type: markdown
content: "**Next up:** the weekly digest"Widget Reference
| Type | Required fields | Renders as |
|---|---|---|
| metric | label, value | A number, with optional unit, trend (up/down), trend_value, description — and a sparkline when it has an id |
| status | label, value, color | A colored badge (green, red, yellow, gray, blue, orange, purple) |
| progress | label, value | A 0–100 bar, optional color; history and sparkline when it has an id |
| text | content | Plain text, optional size, color, align |
| markdown | content | Rendered Markdown |
| table | columns, rows | A table |
| list | items | A bullet or numbered list |
| link | label, url | A link or button |
| image | src, alt | An image |
| divider | — | A horizontal rule |
| spacer | — | Vertical space |
The eleven types above are the closed set. A widget of any other type — or one missing a required field — is stripped by the agent server before the dashboard reaches the UI and listed in the Dashboard tab's widgets skipped due to validation errors banner; the rest of the dashboard still renders. The agent's compatibility report names the offending type. Only a missing title or an empty sections list makes the whole dashboard invalid.
Sparkline history is keyed by id. Trinity records each metric, progress, and status widget's value whenever dashboard.yaml changes (captured on the next dashboard read, so an unchanged file adds no points); metric and progress widgets draw a sparkline once they have more than one point. A widget with an explicit id keeps its history when you reorder or insert widgets; one without an id is keyed by position (s0_w1), so moving it starts a new series. Trend arrows compare the first and second halves of the window (more than ±5% is up or down).
Declared Metrics
A dashboard.yaml value is whatever the agent last wrote into the file. A declared metric is different: the agent records each observation as a timestamped point, so Trinity holds a real time series and can tell you when the number was last true.
How declared metrics work
template.yaml under metrics: — either by editing the file, or from the agent's Dashboard tab with Declare metric (see Declaring a metric from the UI). Both write the same block. Each entry has a name, a type (counter, gauge, percentage, status, duration, or bytes), a label, and optional fields such as unit, cadence, direction (up_good, down_good, neutral), aggregation (last, sum, avg), and dimensions. A status metric lists its allowed values, each with a color.template.yaml, and when the container starts. An entry Trinity cannot read is dropped and reported as a finding in the agent's compatibility report.record_metrics. Each batch is all-or-nothing: if one point is invalid, the whole batch is refused and each bad point comes back with a reason code. A name the registry does not hold is refused with metric_undeclared.dashboard.yaml widgets. The tab appears when the agent has declared metrics, even with no dashboard.yaml, and always for the agent's owner.Each tile shows the latest value, formatted for its type (a duration of 5400 reads 1h 30m), and when that point was recorded — relative on the tile, exact on hover. Pick a window (Auto, 24 hours, 7 days, 30 days, 90 days) to change the sparkline range. The tiles read only from the point store, so they show the same numbers when the agent is stopped.
Declaring a metric from the UI
The agent's owner, or an admin, can declare, edit and retire metrics without editing files. People the agent is shared with see the tiles but not these controls.
template.yaml inside the agent, so a stopped agent shows Start the agent to change its metrics and nothing is changed.• Label is what the tile shows. Name is suggested from the label; the agent records under it, so it cannot change later.
• What kind of number is it? picks the type: Count, Level, Percentage, Status, Duration or Data size. A Status metric lists its allowed values, each with a colour.
• How often is it recorded? is required. The help line says when the tile turns stale. Custom… takes any fixed length from one minute to 366 days, such as 12h or 3d; use 4w for monthly.
• More options holds thresholds, dimensions, how several series fold together, and an optional Recorded by note. The note is shown on the tile and stored as x-recorded-by.
• What gets added to template.yaml previews the entry.
Errors appear under the field they belong to, using the same checks as a hand edit: a name that is not lowercase letters, digits and underscores, an unknown type, a cadence outside the allowed range, a duplicate name, or a 51st metric. Nothing is written until the form is valid.
dashboard.yaml widgets and project links — and asks you to confirm before removing the entry. Recorded points are kept; declaring the same name again brings them back.template.yaml while the form was open, saving is refused and Reload and keep my entries applies your entries to the latest file.metrics: block written as a one-line list or with YAML anchors cannot be edited by the form. It says so; edit the block in Files instead.template.yaml cannot be parsed, the form changes nothing and no metric is retired.Freshness
Trinity has one staleness rule: a metric is stale when no point has arrived within twice its declared cadence (for example cadence: 1h or cadence: 1d, between one minute and one year). A stale tile keeps its last value and adds a warning chip naming the cadence it missed. It is never shown as current.
| Situation | What you see |
|---|---|
| Recorded within 2× cadence | The value, with its time |
| No point within 2× cadence | The last value, marked stale |
No cadence declared | The value, with a neutral No cadence declared chip — never stale |
| Declared but never recorded | No value yet, with a hint naming the next step |
Binding a widget to a declared metric
A metric, status, or progress widget in dashboard.yaml can name a declared metric instead of carrying its own number:
- type: metric
label: "Revenue"
metric: revenue # a name from template.yaml metrics:
value: 0 # placeholder for agents on an older base imageTrinity fills the widget's value, status color, and sparkline from the recorded points on every read, and marks it stale by the same rule as the tiles. A bound widget whose name is not declared, or whose metric was retired, shows the reason instead of a number.
A bound widget does not need the fields the binding fills: value for metric and progress, and value plus color for status. It still needs its label. The agent server and the compatibility report apply the same rule, so a bound widget without a value is neither stripped nor reported as missing a field — even when the name it binds is undeclared. Agents on a base image built before this feature still require a value: (and a status color:), so keep a placeholder until the image is rebuilt; Trinity overwrites it whenever the binding resolves, and drops it while the metric store is unavailable, so the placeholder is never shown as a real number. Agents scaffolded with the create-agent plugin write these placeholders by default.
A bound metric tile whose metric declares direction: up_good or down_good and a warning_threshold or critical_threshold shows a Critical or Warning badge when its value crosses one (hover it for the threshold). A bound widget's trend arrow and sparkline follow the metric's direction: a rising down_good cost is red, and a metric with no direction declared shows a neutral grey arrow. Any trend: or trend_value: written in the file is replaced by the computed trend once the binding resolves.
One series per tile: dims:
A metric with dimensions holds one series per dimension value, for example one per ad channel. A bound widget without dims: shows the metric's folded number (the sum or avg of every series, or the newest series for last), and a caption says so: sum of 3 channel values, or newest of 3: channel=meta. To show one series, name it with dims:. This recipe takes about five minutes on a running agent.
template.yaml:metrics:
- name: ad_spend
type: gauge
label: "Ad spend"
unit: "USD"
cadence: 1h
direction: down_good
aggregation: sum
critical_threshold: 500
dimensions: [channel]POST /api/agents/{name}/metrics/definitions/refresh, or restart the agent).record_metrics:{"points": [
{"metric": "ad_spend", "value": 587.25, "dims": {"channel": "meta"}},
{"metric": "ad_spend", "value": 410.0, "dims": {"channel": "google"}},
{"metric": "ad_spend", "value": 95.5, "dims": {"channel": "linkedin"}}
]}dashboard.yaml:title: "Spend"
sections:
- title: "Spend by channel"
widgets:
- type: metric
label: "Meta"
metric: ad_spend
dims: {channel: meta}
value: 0 # placeholder, only for an older base image
- type: metric
label: "Google"
metric: ad_spend
dims: {channel: google}
value: 0
- type: metric
label: "LinkedIn"
metric: ad_spend
dims: {channel: linkedin}
value: 0The three tiles show three different numbers (587.25, 410, and 95.5), each with its own point time, stale mark, and sparkline, and each captioned with its series (channel=meta). Each tile is judged on its own number, so only Meta, at or above the 500 critical threshold, shows a Critical badge.
Rules for a selector:
dimensions, so what counts is the dims on the recorded points. On a metric with dimensions: [channel, geo], if the points carry {channel: google, geo: us}, then dims: {channel: google} is refused, and the hint shows the full series (channel=google, geo=us). If the points carry only {channel: google}, that same selector matches. Key order does not matter.dims: {year: "2024"}, dims: {enabled: "yes"}.dims: {} means no selector. The tile shows the folded number. A series recorded with no dims at all cannot be selected on its own.geo to dimensions, update the producers and the selectors together, then check each tile.dims: needs a Trinity backend at or after this release. An older backend ignores it and shows the folded number.A tile whose selector cannot match shows a reason instead of a number, never the folded total:
| What the tile says | Why |
|---|---|
dims must be a mapping of dimension: value, or dims value for 'channel' must be text, with a hint | The selector is malformed. Fix it as the hint says. |
dimension 'region' is not declared for this metric; declared: channel | The key is not in the metric's dimensions. |
A grey footer: channel=tiktok, no recent data, and a hint | No recent series matches. The channel may not have reported yet, or the value may be misspelled (the hint suggests a casing fix). Each dims: tile reads its own series, so a channel that reports rarely still shows its number next to a busy one; it reads no recent data only when it has had no point for 90 days. |
The agent's compatibility report also flags a dims: selector that can never match, and a metric: that is not a name (check X-009), so an agent can catch the mistake without opening the dashboard.
Visible change for existing dashboards: with no change on your side, a bound tile over several series gains a caption saying what its number is, a breached bound metric tile gains a verdict badge, and bound trend arrows follow the metric's direction. A bound tile over a single series gets no caption. Adding dims: replaces the fold caption with one naming the selected series (for example channel=meta).
Retention and limits
Recorded points are kept for metrics_retention_days (default 365; 0 keeps them forever). Each agent may record up to metrics_daily_point_cap points per UTC day (default 100,000; 0 is unlimited), and up to 1,000 points per call. Both are operator settings (PUT /api/settings/ops/config); until a value is saved, METRICS_RETENTION_DAYS and METRICS_DAILY_POINT_CAP in .env supply it. GET /api/settings/retention reports the effective values and where each comes from; some editions also show them as rows in Settings → Retention. See Monitoring.
Retired: metrics.json
Older agents wrote a metrics.json file into their workspace. Trinity no longer reads it, and does not fall back to it when no points exist. An agent that still writes one gets a compatibility finding naming the file's keys and which of them are not declared. Declare those keys in template.yaml, switch to record_metrics, then delete the file.
Objectives: Target vs Actual
An objective sets a target for a declared metric. Objective files live in the agent's canon under objectives/*.yaml and name each metric by the same name as its metrics: entry:
id: q4-close-rate
statement: Lift close rate to 35% by the end of Q4.
owner: role:revenue-lead
supporting_agents: [sales-companion]
metrics:
- name: close_rate
direction: up # up | down | hold
target: 35
by: 2026-12-31
guard_metrics: # optional: numbers that must not move meanwhile
- name: cost_per_lead
target: 40 # the level to hold, once there is a baseline
tolerance: 5
status: activeThe join needs only the agent's canon declaration (x-canon in template.yaml). Trinity reads the active objectives the agent owns or supports, and joins each metric to its latest recorded value and freshness.
owner: role:<id> names the agent's seat on record: the seat the agent holds itself, or else the seats held by the people it serves, its primary first. The x-role entry in template.yaml does not decide this. An agent with no seat owns nothing and gets a no_seat finding that says what to do; objectives that name it in supporting_agents still show.role: "guard", and is always judged as a hold — on_target within its tolerance or off_target — whatever direction the metric declares elsewhere. Guards are counted in summary.guards, apart from the objective's own metrics, so an objective without guards reports exactly as before. A guard list that is not a list (guard_metrics_invalid), a guard with no target yet (guard_target_unset) or a guard given a direction (guard_direction_invalid, the word is ignored) is named as a finding.Each row reports the target, the actual, whether it is stale, and a gap:
gap.status is position, not pace: behind, on_target, or ahead for up and down; on_target or off_target for hold. It never says whether the agent is late against by.stale: true beside it.Objective files are read from the agent's container on each request, so a stopped agent answers unavailable: agent_stopped.
Related: the Brain Orb
The dashboard.yaml widgets above are one way an agent renders its own state. Knowledge-base agents — like the bundled Cornelius second-brain — can also publish a Brain Orb: a self-rendering "mind" page that draws the agent's own notes, edges, and activity as a live 3D knowledge graph on the agent's Brain tab.

The Brain Orb is a capability-gated surface: it appears only for agents that ship the brain-orb capability (Cornelius-class agents) and only when the platform Brain Orb flag is enabled — it is off by default. An admin turns it on under Settings → General → Brain Orb (or BRAIN_ORB_ENABLED); a saved setting overrides the environment variable and applies without a restart. The agent owns generation and scope state; Trinity reads and renders it.
For Agents
Agents control their dashboard entirely by writing to dashboard.yaml in their workspace. No API call is needed to publish changes — the file is read on each dashboard request. Declared metrics are the exception: record them with record_metrics.
MCP Tools
These tools act on the calling agent's own metrics. An agent records only its own points. It can read another agent's metrics with get_metrics(agent=...) only while it holds a permission grant on that agent — the same grant chat_with_agent uses.
| Tool | Description |
|---|---|
| record_metrics(points, execution_id?) | Record up to 1,000 points ({metric, value, ts?, dims?}) against declared metrics. A point's identity is (metric, ts, dims): re-sending the same value deduplicates, and a different value at the same identity corrects the stored point in place (reported as corrected). Pass execution_id so a re-delivered turn replays instead of recording twice; an optional idempotency_key makes a re-sent identical batch return the first result. Never throws — refusals come back with a reason code per point |
| refresh_metric_definitions() | Re-read template.yaml and reconcile the registry after you change metrics:. Needs the agent running |
| get_metrics(agent?, metric?, window?, since?, until?, include_retired?) | Declared metrics with the latest value, freshness, and a bounded series (up to 120 buckets each). Name one metric for its raw points, newest first. agent reads another agent's metrics (needs a permission grant on it; otherwise refused, not retryable) |
| get_objectives() | Your objectives joined to your metrics, guards included: target, actual, freshness, and gap. Use it instead of computing a gap from get_metrics. A metric you do not declare yourself can still get an actual when exactly one agent you hold a grant on serves it |
API
| Endpoint | Method | Description |
|---|---|---|
| /api/agent-dashboard/{name} | GET | Get dashboard data, enriched with history and platform metrics |
| /api/agent-dashboard/{name}/exists | GET | What the Dashboard tab would show: has_dashboard (a cached dashboard.yaml) and has_declared_metrics. No container call, so it answers for a stopped agent |
| /api/agents/{name}/metrics | GET | Declared metrics with latest values, freshness, and series. window = auto|24h|7d|30d|90d, or since/until; metric for one metric's raw points; include_retired. An undeclared metric is a 422 metric_undeclared. An agent key reading another agent needs a permission grant on it (403 otherwise) |
| /api/agents/{name}/metrics/points | POST | Record a batch of points (what record_metrics calls). Accepts Idempotency-Key. 422 lists a reason per bad point; 429 on the per-minute rate or the daily cap |
| /api/agents/{name}/metrics/definitions | GET | The declared-metric registry as Trinity reconciled it (include_retired for retired names). Same grant rule as /metrics |
| /api/agents/{name}/metrics/definitions/refresh | POST | Re-read template.yaml into the registry. 409 if the agent is stopped; 503 leaves the registry unchanged if the file cannot be read |
| /api/agents/{name}/objectives | GET | Objectives joined to metrics: target, actual, freshness, gap, and findings |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| include_history | bool | Include historical value data (default true) |
| history_hours | int | Hours of history to return, 1–168 (default 24) |
| include_platform_metrics | bool | Include the auto-injected platform metrics section (default true) |
Limitations
type is frozen once points exist under its name. To change the shape, rename the metric.get_objectives has no agent parameter: an agent reads only its own objectives.cadence. Without one, Trinity cannot tell you that a number has gone quiet.