Skip to main content
Back to how-to guides Set type: on a GATHER field to make the agent accept only values of that type. The runtime converts the customer’s wording to a clean value, rejects what it cannot convert, and asks again.

Concept

A customer types free text. A field with a type turns that text into a typed value before the agent stores it. For every collected value, the runtime does this in order:
  1. Normalize. It converts spoken or formatted input: “twelve” becomes 12, “(415) 555-0100” becomes +14155550100, “tomorrow” becomes an ISO date.
  2. Check the type. It rejects values that cannot be converted, such as “maybe” for a boolean.
  3. Check the date direction. A date field with semantics: temporal rejects dates on the wrong side of today.
  4. Apply your validate: rule, if the field has one.
  5. Store or re-ask. A valid value is stored. An invalid value is dropped, the field stays missing, and the agent asks again.
A rejected value never reaches COMPLETE, tool inputs, or handoffs. Typing a field is the first and cheapest line of defense. Use validate: only for rules a type cannot express.

Field types

Type names are not case-sensitive. A type the runtime does not know, such as colour, compiles without a warning and accepts any value. Check the spelling.

Minimal working example

A newsletter agent collects an email address and a team size. Both are checked by type. agents/newsletter-signup.agent.abl
Variable sources:
  • email and seats are GATHER fields. The customer supplies both.
  • COMPLETE reads both fields in its condition and its reply.
A customer who answers “ann@example” is asked again. A customer who answers “we are twelve” gets seats = 12.

How it works

The same checks run in a top-level GATHER and in a GATHER inside a FLOW step. They differ in how the re-ask reaches the customer. Reasons for REASONING: false steps, with the MESSAGES key that overrides each: The reason never quotes the rejected value when the field is sensitive: true.

Realistic example

A warranty agent collects six typed fields. The purchase date must be in the past. The repair cost is optional. agents/warranty-claim-intake.agent.abl
Variable sources:
  • All variables are GATHER fields. The customer supplies each one.
  • repair_cost is optional and is not read in COMPLETE.

Common variations

Deterministic re-ask in a FLOW step

Use a FLOW step with REASONING: false when the re-ask wording must be the same every time. Override the default reason in MESSAGES. agents/callback-booking.agent.abl
A phone number with no region is read as a US number. When the session locale carries a region, such as fr-CA, that region is used instead.

Ranges and lists

Add range: true to collect a low and high value. Add list: true to collect several values. Each endpoint or item is checked against the field type. One bad item rejects the whole value. This is a section snippet.
A text list splits a reply on commas. A list of numbers or dates does not: one string such as “1, 2, 3” is rejected, so the items must be extracted as separate values.

Add a rule on top of the type

A type cannot say “two letters and six digits”. Add a validate: rule for that. The type check still runs first.
validate: accepts a regular expression or enum(a, b, c). retry_prompt and max_retries need a validate: rule. Without one, the compiler reports GATHER_VALIDATION_RULE_REQUIRED. In a FLOW step, retry_prompt replaces the whole re-ask.

Verification

Test each field with a good value, a bad value, and a spoken value. Send these to the agent in a test session, then open the session trace. What to check in the trace:
  • In a FLOW step, the ner_stage_resolution event lists each value with valid: false and the internal error. The customer never sees that error.
  • After max_retries failures, a validation_max_retries event names the field and the retry count.
  • The stored value in the session data is the normalized value, not the customer’s words.

Production readiness checklist

  • Every field has the narrowest type that fits. Use string only for free text.
  • Type names are spelled correctly. A misspelled type disables validation without a warning.
  • Fields that hold secrets or personal data set sensitive: true.
  • Each REASONING: false step has a MESSAGES override for the reasons your customers will see, in every language you support.
  • You decided what happens after repeated failures: a max_retries limit, a trace alert, or a route to a human.
  • You tested a good value, a bad value, a spoken value, and a blank reply for each field.
  • Downstream tools expect the normalized form: E.164 phone, ISO date, lowercase email, number for currency.

Common mistakes

Troubleshooting