# 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](https://docs4.mindset.ai/docs/ams/environments).

## Charts and simple displays need no widget

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

1. Go to **Widgets** and press **+ New widget**.
2. 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."
3. When it has created the widget, press **Open widget →**.
4. Check it on the **Preview** tab, and refine it by talking to the Widget Builder docked beside it.
5. Set its parameters on the **Data** tab.
6. When the builder has made changes, press **Save changes**. This saves a new draft version. Nothing changes for anyone yet.
7. Publish it on the **Versions** tab.
8. 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](https://docs4.mindset.ai/docs/ams/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](https://docs4.mindset.ai/docs/ams/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](https://docs4.mindset.ai/docs/ams/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.