A built-in tool that enables agents to request structured input from users via interactive forms

Collect User Input

The collect_user_input tool is a built-in system tool that allows agents to request structured information from users through interactive forms. Instead of parsing free-text responses, agents can present users with clear options, text fields, date pickers, and more.

Why Use Collect User Input?

Free-text conversations work well for simple questions, but structured input is better when you need:

Precise data — Dates, numbers, or specific choices that are hard to extract from natural language
Multiple fields at once — Collect several pieces of information in a single interaction
Clear options — Present users with defined choices instead of hoping they guess the right format
Validated input — Ensure required fields are filled and values are in the expected format

How It Works

Agent decides to collect input — Based on the conversation, the agent determines it needs specific information
Form appears — An interactive form slides up from the chat input area
User fills in the form — The user provides the requested information or cancels
Agent receives structured result — The agent gets a clean JSON object with the user's responses

Field Types

The tool supports five field types:

Choices

Single or multi-select from a list of options.

{
  "type": "choices",
  "name": "priority",
  "label": "Select priority level",
  "options": [
    { "label": "Low", "value": "low" },
    { "label": "Medium", "value": "medium", "description": "Default for most tasks" },
    { "label": "High", "value": "high", "description": "Urgent items only" }
  ],
  "multiSelect": false,
  "required": true
}

Property	Type	Description
`options`	array	List of choices with `label`, `value`, and optional `description`
`multiSelect`	boolean	Allow selecting multiple options (default: false)
`defaultValue`	string or string[]	Pre-selected value(s)

Text

Free text input, optionally multiline.

{
  "type": "text",
  "name": "description",
  "label": "Describe the issue",
  "placeholder": "Enter details here...",
  "multiline": true,
  "required": true
}

Property	Type	Description
`placeholder`	string	Hint text shown when empty
`multiline`	boolean	Show a textarea instead of single-line input
`defaultValue`	string	Pre-filled text

Number

Numeric input with optional min/max constraints.

{
  "type": "number",
  "name": "quantity",
  "label": "How many items?",
  "min": 1,
  "max": 100,
  "required": true
}

Property	Type	Description
`min`	number	Minimum allowed value
`max`	number	Maximum allowed value
`defaultValue`	number	Pre-filled number

Checkbox

Boolean yes/no toggle.

{
  "type": "checkbox",
  "name": "agreeToTerms",
  "label": "I agree to the terms and conditions",
  "defaultValue": false
}

Property	Type	Description
`defaultValue`	boolean	Initial checked state

Date

Date picker returning ISO format (YYYY-MM-DD).

{
  "type": "date",
  "name": "startDate",
  "label": "When should this start?",
  "required": true
}

Property	Type	Description
`defaultValue`	string	Pre-filled date in ISO format

Form Configuration

When calling the tool, agents specify the form structure:

{
  "title": "Schedule a Meeting",
  "description": "Please provide the meeting details",
  "fields": [
    {
      "type": "text",
      "name": "meetingTitle",
      "label": "Meeting title",
      "required": true
    },
    {
      "type": "date",
      "name": "date",
      "label": "Date",
      "required": true
    },
    {
      "type": "choices",
      "name": "duration",
      "label": "Duration",
      "options": [
        { "label": "30 minutes", "value": "30" },
        { "label": "1 hour", "value": "60" },
        { "label": "2 hours", "value": "120" }
      ]
    }
  ],
  "submitLabel": "Schedule",
  "cancelLabel": "Cancel",
  "allowFreeformResponse": true
}

Property	Type	Default	Description
`title`	string	—	Form header text
`description`	string	—	Explanatory text below the title
`fields`	array	(required)	Array of field definitions
`submitLabel`	string	"Submit"	Text for the submit button
`cancelLabel`	string	"Cancel"	Text for the cancel button
`allowFreeformResponse`	boolean	true	Show "Or type a response instead..." option

Response Handling

The agent receives one of three response types:

Submitted Values

User filled out the form and clicked submit:

{
  "values": {
    "meetingTitle": "Project Review",
    "date": "2024-03-15",
    "duration": "60"
  }
}

Cancelled

User clicked cancel:

{
  "cancelled": true
}

Freeform Response

User chose to type a text response instead of using the form:

{
  "freeformResponse": "Actually, can we do this next week instead? I'm out of office."
}

Best Practices

Keep Forms Focused

Limit to 3-5 fields per form
Only mark fields as required when truly necessary
Use sensible defaults when possible

Choose the Right Field Type

Need	Use
Yes/no question	`checkbox`
Pick from known options	`choices`
Open-ended short answer	`text`
Open-ended long answer	`text` with `multiline: true`
Amount, quantity, count	`number` with `min`/`max`
Calendar date	`date`

Provide Helpful Context

Use clear, concise labels
Add descriptions to choice options when the meaning isn't obvious
Include placeholder text for text fields
Use the form description to explain why you're asking

Handle All Response Types

Always handle all three response types in your agent's logic:

Values — Process the structured data
Cancelled — Acknowledge and don't immediately re-ask
Freeform — Parse the text and adapt accordingly

Allow Freeform When Appropriate

The allowFreeformResponse option lets users type a response instead of using the form. This is useful when:

Users might have context that doesn't fit the form fields
The situation might have changed since the agent asked
Users prefer typing over clicking

Disable it when you strictly need structured data (e.g., for API calls with specific parameter formats).

Use Cases

Order Collection

{
  "title": "Complete Your Order",
  "fields": [
    {
      "type": "choices",
      "name": "size",
      "label": "Size",
      "options": [
        { "label": "Small", "value": "S" },
        { "label": "Medium", "value": "M" },
        { "label": "Large", "value": "L" }
      ],
      "required": true
    },
    {
      "type": "number",
      "name": "quantity",
      "label": "Quantity",
      "min": 1,
      "max": 10,
      "defaultValue": 1,
      "required": true
    },
    {
      "type": "checkbox",
      "name": "giftWrap",
      "label": "Add gift wrapping (+$5)"
    }
  ]
}

Feedback Collection

{
  "title": "How was your experience?",
  "fields": [
    {
      "type": "choices",
      "name": "rating",
      "label": "Overall rating",
      "options": [
        { "label": "Excellent", "value": "5" },
        { "label": "Good", "value": "4" },
        { "label": "Average", "value": "3" },
        { "label": "Poor", "value": "2" },
        { "label": "Very Poor", "value": "1" }
      ],
      "required": true
    },
    {
      "type": "text",
      "name": "comments",
      "label": "Additional comments",
      "multiline": true,
      "placeholder": "Tell us more about your experience..."
    }
  ],
  "submitLabel": "Send Feedback"
}

Appointment Scheduling

{
  "title": "Book an Appointment",
  "description": "Select your preferred date and time slot",
  "fields": [
    {
      "type": "date",
      "name": "appointmentDate",
      "label": "Date",
      "required": true
    },
    {
      "type": "choices",
      "name": "timeSlot",
      "label": "Available times",
      "options": [
        { "label": "9:00 AM", "value": "09:00" },
        { "label": "11:00 AM", "value": "11:00" },
        { "label": "2:00 PM", "value": "14:00" },
        { "label": "4:00 PM", "value": "16:00" }
      ],
      "required": true
    },
    {
      "type": "text",
      "name": "notes",
      "label": "Notes for the appointment",
      "placeholder": "Any special requests or information..."
    }
  ],
  "submitLabel": "Book Appointment"
}

Technical Details

The collect_user_input tool is a client-side tool. When the agent calls it:

The tool call is streamed to the client (chat widget)
The client renders the form overlay
The user interacts with the form
The client sends the result back via the tool result mechanism
The agent receives the result and continues

This means the tool works automatically with the Ensemble chat widget. If you're building a custom chat interface, you'll need to handle the collect_user_input tool call and render your own form UI.

Collect User Input

On this page