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.