Form Builder

Attach a structured data-collection form to an AI Agent in Synthreo Builder — field types, Static and DCS-backed lists, Custom JS, settings, save and test workflow.

Overview

The Form Builder lets you attach a structured data-collection form to an AI Agent. When end users open the agent in a supported host (such as ThreoAI), they can complete the form first; submitted values become structured input for your workflow alongside or instead of a single free-text message.

Use a form when you need predictable fields—IDs, dates, uploads, constrained choices—before the agent runs.

Tip: Configuring the form does not change your node graph. You can add, edit, or remove fields without rewiring nodes; you only need to align prompts and variables with the field names you define (see How field names connect to your workflow).

Accessing the Form Builder

In Builder, go to All Bots → AI Agents and open the agent you want to configure.
Open the workflow canvas (hyper-graph) for that agent.
In the header toolbar under the agent name, click the Form Builder control: the field chooser icon (tooltip Form Builder).
The Form Builder opens as a modal over the canvas—you stay on the same page.

There is no separate documentation URL for the Form Builder; it is always opened from the agent canvas toolbar.

Form Builder interface

The dialog has three tabs and action buttons at the bottom.

Tabs

Tab	Purpose
Fields	Add, edit, reorder, and delete form fields. This is where you build the form structure.
Custom JS	Optional JavaScript for dynamic behavior in the client (for example conditional visibility or extra validation), where supported by the host.
Settings	Turn the form on or off, configure a custom confirmation message after submit, and optional fire-and-forget submit behavior.

Actions

Add Field — Opens the Field Details dialog to create a new field.
Save — Saves the form configuration to the agent and closes the dialog on success.
Cancel — Closes the dialog without applying changes from the current session.

The Fields tab

The Fields tab shows a table of all fields with these columns:

Column	Description
Name	Internal identifier used when values are passed into the agent (see below).
Label	Text shown to end users above the control.
Data Type	The field type; for some types you also see mode or data source (for example DCS).
Required	Whether the field must be filled before submit.
Actions	Edit (pencil) or delete (trash).

When no fields exist yet, the table is empty—use Add Field to create the first one.

Reordering fields

You can drag rows by the row-drag handle to change order. That order is the order fields are typically shown to end users and the order stored in the form configuration.

Adding a field

Click Add Field.
In Field Details, complete the General section (see the next subsection).
Configure any type-specific sections that appear for the selected data type.
Click Save in the Field Details dialog to add the field to the table, or Cancel to discard.

General settings (all types):

Setting	Description
Name (required)	Internal variable name. Must be unique among fields. Use letters, numbers, and underscores (for example `customer_name`). Avoid spaces.
Label (required)	User-visible label (for example Customer name).
Data Type (required)	Determines the control and the extra options shown. See Field data types.
Required	If enabled, the user must provide a value before submit (subject to host validation).
Read Only	If enabled, the value may be shown but not edited—useful for pre-filled display-only data.

Editing a field

Click the Edit (pencil) action for the row. Change settings and click Save in Field Details.

Deleting a field

Click Delete (trash). The row is removed from the list immediately.

Warning: Removal is not automatically undone. If you delete by mistake, close the Form Builder with Cancel (without saving the Form Builder dialog) only if you have not saved other changes you need to keep.

Field data types

The Data Type dropdown selects one of eight types. Each type drives which control the user sees and which extra options appear in Field Details.

Data type	Typical control	Notes
`string`	Single-line or multi-line text	Mode, length, placeholder, optional regex
`bool`	Checkbox	No type-specific section beyond General
`number`	Numeric input	Optional minimum and maximum
`array`	Dropdown, tag box, or multi-select	Static list or DCS-backed options
`file`	File upload	Extensions and max size
`image`	Image upload	Same options as file
`date`	Date picker	Default date and placeholder
`screen_recording`	Screen capture	No type-specific section beyond General

String — text input

String options:

Option	Description
Mode	`text` (default) or `password` (masked input).
Max Length	Maximum number of characters. The control enforces a positive minimum in the Field Details UI; treat “unlimited length” as a product-specific case and verify in-app if you need it.
Placeholder	Hint text when the field is empty.
Multi-line	When enabled, the field is a text area.
Rows	Shown when multi-line is enabled—controls the height of the text area.
Regex Validator	Optional pattern; input must match before submit.

Bool — boolean

A single checkbox; value is true or false. Use for yes/no questions, consent, or toggles. No extra options beyond General.

Number — numeric input

Number options:

Option	Description
Min	Optional lower bound.
Max	Optional upper bound.

Leave bounds unset when you do not need a range.

Array — selection list

Array modes:

Mode	Description
select	Single choice from a dropdown.
tagbox	Searchable selection shown as a tag.
multi-select	Multiple choices from the list.

Data source — Static

Use Static for a fixed list of options. The UI uses a tag-style entry control: you add discrete options. You can enter multiple values in one go using comma-separated text (commas that are not followed by a space are treated specially for splitting—use the in-product behavior when bulk-adding labels that contain commas).

Data source — DCS (Dynamic)

Use DCS (Dynamic) when options should come from your Data Studio data. Configure:

Field	Description
Database	The data connection (system).
Table	The table (data frame) to read from.
Display Column	Column whose values the user sees.
Value Column	Column whose values are submitted (can differ from the display column, for example show a name but submit an ID).

Available connections depend on your organization’s DCS configuration.

File — file upload

Option	Description
Allowed Extensions	Comma-separated list (for example `pdf,docx,xlsx`). Leave blank only if your policy allows any type.
Max Size (MB)	Maximum file size. The Field Details control uses a positive minimum; confirm in-app if you need very large uploads.

Image — image upload

Same configuration pattern as file. For images only, restrict extensions (for example jpg,jpeg,png,gif,webp) in Allowed Extensions.

Date — date picker

Option	Description
Default Value	Optional pre-selected date.
Placeholder	Hint when no date is selected.

Screen recording

Lets the user capture and submit a screen recording. No extra options beyond General. Useful for support scenarios where a video reproduces an issue.

Tip: Screen recording requires the user to grant capture permission—use sparingly.

Custom JS tab

The Custom JS tab contains a code editor for JavaScript stored with the form. Common uses:

Showing or hiding fields based on other fields
Deriving or mirroring values between fields
Extra client-side validation beyond built-in rules

Security: Scripts run in the user’s browser in the host environment. Do not embed secrets. Test thoroughly before publishing.

Tip: Leave this tab empty if you do not need dynamic behavior.

Settings tab

Setting	Description
Form is active	When enabled (default), the form is used for the agent where the host supports it. Disable to turn the form off without deleting field definitions.
Respond with custom message	When enabled, a rich HTML editor appears. After submit, the user can see this message instead of the default immediate reply (behavior depends on host integration).
Fire and forget submit	When enabled, submit may return immediately while the agent continues processing in the background—often paired with a custom confirmation message for data-collection flows.
Rich text editor	Available when Respond with custom message is on—formatted confirmation content (headings, lists, links, images, tables, and so on).

Saving the form

Make changes on any tab (Fields, Custom JS, Settings).
Click Save at the bottom of the Form Builder dialog to write the configuration to the agent.

After saving:

If the agent is Online, use Restart in the agent toolbar so the running instance picks up the new configuration (same as other agent settings).
Use Test in Builder to exercise the agent and form in the test environment before relying on production traffic.

Warning: Cancel or closing without Save discards unsaved changes in the Form Builder session.

If you also edited the node graph, save the canvas separately—the Form Builder only updates the form definition attached to the agent.

Testing and rollout

Run Test from the agent toolbar to verify required fields, validation, and Custom JS.
After Save on the form and Restart when needed, spot-check in ThreoAI (or your production host) as a final step.

Best practices

Naming fields

Prefer lowercase, numbers, and underscores in Name (for example order_id, contact_email).
Keep Name stable once workflows or integrations rely on it.
Use Label for friendly, human-readable text.

Required fields

Mark Required only when the downstream workflow truly needs the value—optional fields reduce friction.

Choosing types

Use string for general text; enable Multi-line for long text.
Use bool for yes/no or consent.
Use number when the value must be numeric with optional bounds.
Use array with Static for fixed lists; DCS when options must track live data.
Use file / image with Allowed extensions and max size to reduce abuse.
Use screen_recording only when video adds clear value.

How field names connect to your workflow

Each field’s Name is the usual key for that value in the structured payload the host sends into the agent. When you build prompts or reference input in nodes, align variable usage with those keys and with your Input Data configuration (for example JSON payloads). For a broader picture of how agents receive input, see the User manual.

Quick reference

Type	Typical options to remember
`string`	Mode, max length, placeholder, multi-line, rows, regex
`bool`	(General only)
`number`	Min, max
`array`	Mode, Static vs DCS, items or DCS columns
`file` / `image`	Allowed extensions, max size (MB)
`date`	Default value, placeholder
`screen_recording`	(General only)

Checklist — new form from scratch

Open the agent on the workflow canvas.
Open Form Builder from the toolbar.
Add fields with Add Field and Save each Field Details dialog.
Drag rows to set order.
Optional: Custom JS, then Settings (active + message).
Save the Form Builder dialog.
Restart the agent if it is Online.
Test end-to-end, then verify in your production host if applicable.

User manual — Builder workspace, nodes, and variables
Welcome to Builder — Platform overview