Docs / AMS / Build / Build a widget

Build a widget

Build a widget with the Widget Builder, give it the parameters an agent fills in, publish it, and put it in an agent's conversations.

After this page you can build a widget, decide what an agent supplies to fill it, publish it, and have the invoice exceptions agent show it in a conversation.

What this is

A widget is a small piece of interface an agent shows inside a conversation: a table, a summary card, a form, a chart. You design it once. Each time the agent shows it, the agent fills it with data for that moment.

For the invoice exceptions agent, a widget can show the invoice lines next to the purchase order lines, with each difference marked, instead of describing them in a paragraph.

Widgets live under Widgets in the rail. Each belongs to one environment.

Every agent can already draw a few things in a conversation without a widget:

Tool	What it shows
`render_chart`	A bar, line or pie chart from numbers the agent supplies
`show_table`	A sortable table
`show_callout`	One highlighted box: info, success, warning or danger
`show_ui`	One small card, badge or headline number

Mindset offers these only when a person is watching the conversation and driving it. A scheduled run, a delegated task or a call from another system gets none, because nothing would draw them. The numbers in these charts come from the model, so treat them like the model's prose.

Build a widget when you want the same layout every time, with parameters the agent must fill in correctly.

Build one

Go to Widgets and press + New widget.
In the New widget dialog, tell the Widget Builder what you want. For example: "A table of invoice lines against purchase order lines, with quantity, unit price and total for each, and the lines that differ marked."
When it has created the widget, press Open widget →.
Check it on the Preview tab, and refine it by talking to the Widget Builder docked beside it.
Set its parameters on the Data tab.
When the builder has made changes, press Save changes. This saves a new draft version. Nothing changes for anyone yet.
Publish it on the Versions tab.
Add it to the agent (below).

The Widget Builder can search a library of about 40 curated widget examples, such as an overdue invoices table, a purchase order sign-off and a refund decision. It can also check a widget by rendering it against data and reporting what came out.

The tabs

Tab	What it's for
Preview	The widget, drawn with its sample data. ✎ Edit switches to Edit mode, where you change it in place. The Preview and Document toggle switches to a written description of the widget
Data	The widget's parameters. Each has a Name, a Type (Text, Number, Yes or no, List or Object) and a Description, which tells the agent what to supply. Save parameters saves them as a new draft version. The tab also shows the contract the agent sees
Versions	Every version, each marked Active, Published or Draft, with Publish, Re-activate and Unpublish
Settings	The name, description and category, with Save settings, and Delete widget

The sample data on Data is for the preview only. It never reaches a conversation. In a conversation, the agent supplies every parameter.

Put it in a conversation

Add the widget to the agent on its Resources tab, in the Widgets card, with Add. The widget becomes a tool the agent can call. Its parameters are the tool's arguments, and their descriptions tell the agent what to put in each.

When the agent calls it, Mindset checks the data against the widget's parameters. Data in the wrong shape is refused with the reason, never quietly changed or dropped. A button in a widget can send an action back to the agent, which starts its next turn.

The widget is part of the agent's version, so save and activate the agent version for it to reach people. See Create an agent.

In a script

A script phase that lists its resources can include widgets. The agent is offered a widget only in the phases that list it. For the invoice script, list the comparison widget in Gather, where the differences are found, and leave it out of the other phases. See Write a script.

Publish and roll back

A conversation always shows the widget's active version. Each turn uses whatever version is active at that moment, so a published change reaches conversations already in progress on their next turn. A widget with no active version can't be shown.

To	Do this on Versions
Make a draft live	Publish on that version
Go back to an earlier published version	Re-activate on that version
Take the widget offline	Unpublish. It returns to draft and can't be shown until you publish a version again

After a Re-activate, the Preview shows the live version again, unless a newer draft is waiting.

An agent version records which widgets the agent uses, not which version of each. Activating an earlier agent version doesn't bring back an earlier version of a widget. Use Re-activate for that. For how each kind of change reaches people, see What saving actually does.

What can go wrong

The agent never shows the widget. Check it's published, added on the agent's Resources tab, and listed in the current script phase, and that the agent version is active.
The agent's call is refused. The data didn't match the parameters. Make each parameter's Description say exactly what to supply.
The Preview shows something other than what's live. A newer draft exists. Publish it, or Re-activate the version you want.
A chart doesn't appear in a scheduled run. Nobody is watching a scheduled run, so the drawing tools aren't offered. Have the agent write its answer instead.

You're done when

The widget has parameters with clear descriptions, and the preview looks right.
You published it, added it to the agent and activated the agent version.
You saw the agent show it in a conversation on the Chat tab.
You know which earlier version you'd Re-activate if a change goes wrong.