> ## Documentation Index > Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # agent_dashboard # `agent_dashboard` — agent\_dashboard **Section key** `agent_dashboard` · **Shape** object · **Tier** All plans ## Fields | Field | Required | Type | Allowed values / constraints | Default | Description | | -------------- | -------- | --------------- | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `title` | no | string | — | — | Heading shown above the dashboard. Derived from the spec's root element title on save — not edited directly. | | `enabled` | no | boolean | — | — | Whether the Agent dashboard page renders the spec. | | `spec` | no | object | — | — | A json-render payload \{ root, elements, state? }. Validated by the render catalog (validateRenderPayload), not by this section schema. Bind live values from a data\_source with \{ "\$state": "/pointer" }. | | `data_sources` | no | array of object | — | — | Live-data bindings that populate the spec's state per-viewer. Each entry is exactly ONE of: `tool` (curated read-only built-in — web\_fetch, web\_search, read\_rss\_feed, read\_recent\_tweets, x\_read\_mentions, x\_search\_tweets, calculate — or a custom `type:code` tool, with owner-fixed `params`), `code` (sandboxed body), `url` (an HTTPS endpoint returning JSON/XML that the server fetches + parses), `file` (a JSON/XML file in the agent's dashboard\_data/ directory, kept current by the agent via write\_dashboard\_file), or `db` (a read-only Postgres query). The result is written into the spec state at `result_target` (a JSON Pointer); the browser only ever receives the opaque minted `action_id` — tool/params/code/url/headers/connection strings stay server-side. Agent-push (`writable`) sources are not supported here (use a `file` source + write\_dashboard\_file, or a writable panel on a custom dashboard page). Item fields below. | ### `data_sources` items Live-data bindings that populate the spec's state per-viewer. Each entry is exactly ONE of: `tool` (curated read-only built-in — web\_fetch, web\_search, read\_rss\_feed, read\_recent\_tweets, x\_read\_mentions, x\_search\_tweets, calculate — or a custom `type:code` tool, with owner-fixed `params`), `code` (sandboxed body), `url` (an HTTPS endpoint returning JSON/XML that the server fetches + parses), `file` (a JSON/XML file in the agent's dashboard\_data/ directory, kept current by the agent via write\_dashboard\_file), or `db` (a read-only Postgres query). The result is written into the spec state at `result_target` (a JSON Pointer); the browser only ever receives the opaque minted `action_id` — tool/params/code/url/headers/connection strings stay server-side. Agent-push (`writable`) sources are not supported here (use a `file` source + write\_dashboard\_file, or a writable panel on a custom dashboard page). | Field | Required | Type | Allowed values / constraints | Default | Description | | ---------------------- | -------- | ------ | ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tool` | no | string | — | — | Curated read-only built-in or the name of a custom `type:code` tool on this agent. | | `params` | no | object | — | — | Owner-fixed parameters for the tool. The browser never supplies these. | | `code` | no | string | — | — | Sandboxed code body (alternative to `tool`). | | `language` | no | enum | one of `python`, `javascript` | — | | | `url` | no | string | — | — | HTTPS pull: an endpoint returning JSON/XML/text that the SERVER fetches directly (SSRF-guarded, redirect-validated, size-capped) and parses — ideal for REST APIs and status endpoints. Use with optional `headers` and `format`. Set exactly ONE of tool/code/url/file/db per source. | | `headers` | no | object | — | — | Owner-fixed request headers for `url` (e.g. \{"Authorization": "Bearer …"}). Server-side only — stripped before anything ships to a browser. | | `format` | no | enum | one of `auto`, `json`, `xml`, `text` | — | Body parsing for `url`. auto (default) follows the response content-type: JSON is parsed, XML/RSS/Atom is converted to JSON (attributes under "@"), anything else is JSON-sniffed then served as raw text. | | `file` | no | string | — | — | Local-file pull: a bare filename like "metrics.json" or "report.xml" read from the agent's own dashboard\_data/ directory on every (cached) request. The agent keeps it current with the write\_dashboard\_file tool (code tools: ctx.tools.write\_dashboard\_file); on self-hosted installs any external process may write it. XML is converted to JSON (attributes under "@"). | | `db` | no | object | — | — | Read-only database pull; returns the rows as an array of objects. Connects to the owner's own Postgres with the supplied connection string and runs the query inside a READ ONLY transaction with a statement timeout (writes fail; private/loopback hosts are refused unless the operator allows them in widget-security.json). Connection string + query never leave the server. Item fields below. | | `result_target` | no | string | — | — | JSON Pointer into the spec state to write the result into (e.g. "/data"). The spec then reads it with \{ "\$state": "/data/..." }. | | `result_path` | no | string | — | — | Optional dotted path into the tool result to extract before writing (e.g. "rows"). | | `refresh_interval_sec` | no | number | — | — | Optional auto-refresh cadence in seconds; clamped to \[60, 86400]. | | `action_id` | no | string | — | — | Minted at save time — the only field shipped to the browser. | ### `data_sources.db` fields Read-only database pull; returns the rows as an array of objects. Connects to the owner's own Postgres with the supplied connection string and runs the query inside a READ ONLY transaction with a statement timeout (writes fail; private/loopback hosts are refused unless the operator allows them in widget-security.json). Connection string + query never leave the server. | Field | Required | Type | Allowed values / constraints | Default | Description | | -------- | -------- | ------ | ---------------------------- | ------- | ---------------------------------------------------------------------------- | | `engine` | no | enum | one of `postgres` | — | | | `url` | no | string | — | — | postgres\:// or postgresql:// connection string. Never shipped to a browser. | | `query` | no | string | — | — | The read-only SELECT to run (single statement; writes are rejected). | | `params` | no | array | — | — | Optional bind values for \$1… placeholders. |