type: enum and list the allowed values in options:. The agent stores only one of those values, spelled exactly as you wrote it.
Concept
An enum field limits a customer’s answer to a fixed list. The customer can answer in their own words. The runtime maps the answer to one of your values, or rejects it and asks again. The runtime matches in this order and stops at the first hit:- Exact match with an option.
- Case-insensitive match. “PRO” becomes
pro. - Synonym match. “premium” becomes
pro, if you declared it as a synonym ofpro.
Minimal working example
A support agent collects a ticket priority.agents/ticket-priority.agent.abl
priorityis aGATHERfield. The customer supplies it.COMPLETEreads it in the condition and in the reply.
high. “urgent” is rejected and the agent asks again.
Ways to declare the allowed values
All forms give the same result. Pick one per field.
If a field has both
options and enum_set, options wins.
Rules for the field forms:
- Do not quote values in the inline form.
options: ["iPhone", "iPad"]keeps the quote marks as part of each value. The customer’s “iPhone” then fails to match"iPhone". Write[iPhone, iPad], or use the list form. The list form removes the quote marks. - Do not quote values in
enum(...). The same applies. - Do not combine
entity_refwithtypeoroptions. The compiler reportsGATHER_ENTITY_REF_CONFLICT. - Do not leave
optionsout of atype: enumfield. It compiles with no warning and accepts any value.
Realistic example
A plan-change agent uses four enum forms. The plan tier comes from a shared entity with synonyms.agents/plan-change.agent.abl
- All variables are
GATHERfields. The customer supplies each one. plantakes its values and synonyms from theplan_tierentity.
pro. “starter” is stored as basic. “us” is stored as US.
Accept looser wording
Synonyms cover fixed alternatives. Extraction hints cover phrases you cannot list. A hint tells the model how to map the customer’s words to an option.extraction_hints entry. Without synonyms or hints, a customer who says “my laptop” is asked again.
Common variations
Deterministic re-ask in a FLOW step
In aFLOW step with REASONING: false, a rejected value gets a fixed reason, then the prompt.
agents/laptop-support.agent.abl
MESSAGES entry.
Reuse values across agents
Declare the values once inENTITIES and point each field at them with entity_ref. The Plan_Change example above shows this. A field with entity_ref inherits the type, values, and synonyms. It can still add its own description and extraction_hints.
Multiple choices
Addlist: true to accept several values. Each item must be a valid option. One bad item rejects the whole answer.
How a rejected value behaves
- The value is not stored. The field stays missing.
- In a top-level
GATHER, the runtime tells the model which field failed and which values are allowed. The model words the re-ask. - In a
FLOWstep withREASONING: false, the customer hears thegather_invalid_optionreason, then the field’s prompt. - The reason never lists the allowed values. Put them in the field
prompt.
Verification
Send these in a test session, then open the session trace.
In the trace:
- The
ner_stage_resolutionevent shows each value withvalidand the internal error. - The error “Extracted enum rewrite is not authorized by authored field metadata.” means the model changed the customer’s words into an option and nothing authorized it. Add a synonym or an
extraction_hintsentry.
Production readiness checklist
- Every option is spelled exactly as downstream tools and conditions expect. The stored value is that spelling.
- No option is wrapped in quote marks in the inline form or in
enum(...). - Each enum field has a
promptthat names the options. - Synonyms cover the words customers use for each option.
- Each
FLOWstep with an enum has aMESSAGESoverride in every language you support. - You decided what happens after repeated failures. See Show recovery prompts when validation fails.
- Large or changing lists use a lookup instead. See Validate values using an external lookup API.