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 atype turns that text into a typed value before the agent stores it.
For every collected value, the runtime does this in order:
- Normalize. It converts spoken or formatted input: “twelve” becomes
12, “(415) 555-0100” becomes+14155550100, “tomorrow” becomes an ISO date. - Check the type. It rejects values that cannot be converted, such as “maybe” for a
boolean. - Check the date direction. A
datefield withsemantics: temporalrejects dates on the wrong side of today. - Apply your
validate:rule, if the field has one. - Store or re-ask. A valid value is stored. An invalid value is dropped, the field stays missing, and the agent asks again.
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
emailandseatsareGATHERfields. The customer supplies both.COMPLETEreads both fields in its condition and its reply.
seats = 12.
How it works
The same checks run in a top-levelGATHER 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
- All variables are
GATHERfields. The customer supplies each one. repair_costis optional and is not read inCOMPLETE.
Common variations
Deterministic re-ask in a FLOW step
Use aFLOW 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
fr-CA, that region is used instead.
Ranges and lists
Addrange: 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.
Add a rule on top of the type
A type cannot say “two letters and six digits”. Add avalidate: 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
FLOWstep, thener_stage_resolutionevent lists each value withvalid: falseand the internal error. The customer never sees that error. - After
max_retriesfailures, avalidation_max_retriesevent 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
stringonly 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: falsestep has aMESSAGESoverride for the reasons your customers will see, in every language you support. - You decided what happens after repeated failures: a
max_retrieslimit, 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.