Skip to main content
Widgets and forms let an agent render rich UI inside a web chat instead of replying with plain text. A widget is a structured card (a product carousel, an order tracker, a one-time-code prompt); a form is a typed data-collection panel (inputs, ratings, selects) the user fills in and submits. Both are configured on the agent version and triggered by the LLM during a conversation. These render in the embeddable container described in Web widgets overview. This page covers what the agent can show; the Web widget is where it appears.

​
How the LLM triggers them

Widgets and forms are exposed to the model as tools. The model decides when to call them, fills in the parameters, and the result is delivered to the chat UI.
  • Widgets become a tool named show_<widget_type>_widget (for example show_carousel_widget). The tool’s parameters are the widget’s content fields, so the model both chooses to show the widget and supplies its data in one call.
  • Forms become a tool named show_form_<form_id> (for example show_form_contact_info). The form tool takes no parameters — the field definitions live in the config, and the user fills them in. The tool description defaults to Show the '<name>' form to collect structured data from the user. unless you set a custom description.
The same catalog is available on both transports, with one delivery difference:
On the rich-text path, a form is emitted with type: "form" and the full form definition as its data. A widget is emitted with type: "<widget_type>" and the model-supplied content as its data.

​
Enabling widgets

Widgets are configured under built_in_tools.widgets on the agent version. The allowed field is an optional list of widget types.

​
Widget catalog

WidgetType enumerates the available widgets: Each item in a carousel carries an id, title, and image (required), plus optional link, price, vipPrice (a discounted/VIP price), and rating (a number such as 4.5). The widget itself accepts index (starting item, default 0), window (visible items, default 3), and show_add_to_cart to render an Add to Cart button on each item.

​
List items

A list item carries an id and title (required), plus optional subtitle, image, value (right-aligned text such as a price), strike_value (strikethrough, e.g. an original price), badge, and per-item actions. Each action has a label and an action identifier sent back when clicked, plus an optional dismiss flag (default true) that closes the widget after the click. Set selectable: true to enable multi-select checkboxes and numbered: true to auto-number items; pair multi-select with submit_label (use {n} for the selected count) and submit_action.
Each action_grid item takes an id, label, and action_value (sent back when clicked). The optional icon is one of: suitcase, ruler, truck, credit, headset, star, reload. The grid title defaults to How can I help?.
The status field is one of ordered, shipped, in_transit, or delivered. Required fields are order_id, status, carrier, tracking_number, ordered_date, estimated_delivery, and items (each with name, color, size, quantity).

​
Forms

Forms are configured under built_in_tools.forms. The forms list must contain at least one form, and form IDs must be unique within the agent.

​
Form definition

​
Field types

FormFieldType enumerates the field types:

​
Field reference

The validation regex must be 200 characters or fewer, must compile, and may not contain nested quantifiers (such as (a+)+), which are rejected to avoid catastrophic backtracking.

​
Limits

Web widget overview

The embeddable container where these widgets and forms render.

Text, voice, and quick actions

How the web widget runs in text and voice mode and surfaces quick actions.