Field Types

AgentForms supports 8 field types. Every field shares common properties and has type-specific config options.

Common Properties

All field types share these base properties:

Property	Type	Required	Description
`key`	string	Yes	Identifier used as the key in response `data`
`type`	string	Yes	One of the 8 types listed below
`label`	string	Yes	Display label shown to the user (max 255 chars)
`description`	string	No	Helper text shown below the label
`required`	boolean	No	Whether the field must be filled. Default: `false`
`config`	object	No	Type-specific configuration (see each type below)

text

text Single-line text input

Config Options

Key	Type	Description
`placeholder`	string	Placeholder text
`max_length`	integer	Maximum character count (enforced server-side)
`pattern`	string	Regex pattern (matched with Python `re.match()`)

Example

JSON

{
  "key": "full_name",
  "type": "text",
  "label": "Full Name",
  "required": true,
  "config": {
    "placeholder": "Jane Doe",
    "max_length": 100
  }
}

Response data: "full_name": "Jane Doe" (string)

textarea

textarea Multi-line text input

Config Options

Key	Type	Description
`placeholder`	string	Placeholder text
`max_length`	integer	Maximum character count
`rows`	integer	Display height in rows (default: 4)

Example

JSON

{
  "key": "bio",
  "type": "textarea",
  "label": "Tell us about yourself",
  "config": {
    "placeholder": "A few sentences...",
    "max_length": 500,
    "rows": 6
  }
}

Response data: "bio": "I'm a software engineer..." (string)

number

number Numeric input

Config Options

Key	Type	Description
`min`	number	Minimum allowed value
`max`	number	Maximum allowed value
`step`	number	Increment step

Example

JSON

{
  "key": "rating",
  "type": "number",
  "label": "Rating (1-10)",
  "required": true,
  "config": {
    "min": 1,
    "max": 10,
    "step": 1
  }
}

Response data: "rating": 8 (int if no decimal, float otherwise)

email

email Email address input

Config Options

Key	Type	Description
`placeholder`	string	Placeholder text

Validation: Server-side regex ^[^@\s]+@[^@\s]+\.[^@\s]+$.

Example

JSON

{
  "key": "email",
  "type": "email",
  "label": "Email Address",
  "required": true,
  "config": {
    "placeholder": "you@example.com"
  }
}

Response data: "email": "jane@example.com" (string)

select

select Single-choice dropdown

Config Options

Key	Type	Required	Description
`options`	array of strings	Yes	Allowed values for the dropdown

Validation: The submitted value must be one of the listed options.

Example

JSON

{
  "key": "department",
  "type": "select",
  "label": "Department",
  "required": true,
  "config": {
    "options": ["Engineering", "Design", "Marketing", "Sales"]
  }
}

Response data: "department": "Engineering" (string)

multi_select

multi_select Multiple-choice selection

Config Options

Key	Type	Required	Description
`options`	array of strings	Yes	Allowed values

Validation: Every selected value must be in the options list.

Example

JSON

{
  "key": "skills",
  "type": "multi_select",
  "label": "Skills",
  "config": {
    "options": ["Python", "JavaScript", "Rust", "Go"]
  }
}

Response data: "skills": ["Python", "Rust"] (array of strings)

date

date Date picker

Config Options

Key	Type	Description
`min_date`	string	Earliest allowed date (`YYYY-MM-DD`)
`max_date`	string	Latest allowed date (`YYYY-MM-DD`)

Validation: Must match YYYY-MM-DD format and be a valid calendar date. Bounds checked server-side.

Example

JSON

{
  "key": "start_date",
  "type": "date",
  "label": "Start Date",
  "required": true,
  "config": {
    "min_date": "2026-01-01",
    "max_date": "2026-12-31"
  }
}

Response data: "start_date": "2026-06-15" (string, YYYY-MM-DD)

checkbox

checkbox Boolean checkbox

Config Options

No type-specific config options. The config object can be empty or omitted.

Validation: When required: true, the box must be checked. Values "on", "true", "1" are coerced to true. Unchecked or absent is false.

Example

JSON

{
  "key": "agree_tos",
  "type": "checkbox",
  "label": "I agree to the Terms of Service",
  "required": true
}

Response data: "agree_tos": true (boolean)

SDK Field Builders

The Python SDK provides builder functions that return field dicts, so you don't have to write JSON by hand:

Python

from agentforms import fields

# These return plain dicts ready for create_form()
fields.Text(key="name", label="Name", required=True, max_length=100)
fields.Textarea(key="bio", label="Bio", rows=6)
fields.Number(key="age", label="Age", min=0, max=150)
fields.Email(key="email", label="Email", required=True)
fields.Select(key="dept", label="Dept", options=["Eng", "Sales"])
fields.MultiSelect(key="tags", label="Tags", options=["A", "B", "C"])
fields.Date(key="dob", label="DOB", min_date="1900-01-01")
fields.Checkbox(key="agree", label="I agree", required=True)