Widgets

A widget is a small, generated UI surface — a form, an option list, a card, a chart — that an agent can render inside a conversation instead of plain text. Widgets are authored once in the dashboard and exposed to the agent as a callable tool; the agent decides when to call it based on the widget's name and description, the same way it would call any other tool.

Every widget is a JSON spec with four main parts:

Part	Purpose
ast	The component tree that renders the widget's UI.
variables	Named values the widget reads and (optionally) receives from the LLM tool call.
functions	Named actions — server tool calls, client handlers, chat messages, links, dismiss, or local state updates — wired to components via onClickAction.
states (optional)	Named branches that show or hide parts of the UI based on a variable's value.

An optional defaults object can override declared variable defaults. Runtime values resolve in this order: tool input for a variable marked fromInput, then defaults[name], then the variable's own default. Strings in supported text and form props use {variableName} tokens; rendered text and attributes are escaped. Tokens remain literal in server function arguments.

Building a widget

Open Widgets in the dashboard and create a widget. The editor has four tabs:

• AI builder — describe the widget you want in natural language; the assistant proposes a spec you review and apply.
• Code editor — edit the spec directly, either as JSON or JSX (for the component tree) and JSON or Zod (for the input schema).
• Functions — define the named actions a widget's buttons and inputs can trigger.
• States — define named, conditionally visible branches of the component tree.

Content type

Each widget compiles to one of two content types, set from the Content type field in the code editor's widget settings:

Content type	Behavior
remote-dom (default)	Interactive — Input/Select/Textarea/DatePicker/Checkbox/RadioGroup write into local widget state as the visitor types, and setVariable functions re-render the widget without a round-trip to the LLM.
rawHtml	Static — the widget renders once from its variable defaults and inputs. setVariable is a no-op in this mode; use remote-dom for any widget that needs local interactivity.

Component catalog

The component tree (ast) is built from a fixed set of host components, grouped here by family:

• Data display — Table, TableRow, TableCell, Chart, Badge, ListView, ListViewItem
• Form inputs — Input, Select, Textarea, DatePicker, Checkbox, RadioGroup
• Interactive — Button
• Layout — Box, Col, Row, Card, Spacer, Divider
• Media — Image, Icon
• Text — Title, Text, Caption, Label

The State component (used to render a named, conditionally visible branch) is covered in States.

Publishing

Once a widget's spec validates, use Publish in the editor toolbar and attach it to an agent from the Code tab's widget settings. An attached, published widget becomes available for the agent to call during a conversation like any other tool.