Skip to main content
Back to how-to guides Set 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:
  1. Exact match with an option.
  2. Case-insensitive match. “PRO” becomes pro.
  3. Synonym match. “premium” becomes pro, if you declared it as a synonym of pro.
The runtime does not match parts of words or near misses. “the pro plan” and “pr” are rejected. To accept looser wording, add synonyms or an extraction hint. See Accept looser wording. An enum field stores the canonical option, never the customer’s wording. Conditions and tool inputs can rely on the exact value. For free-form text, see Validate collected fields by type. For format rules, see Validate fields with regex or custom patterns.

Minimal working example

A support agent collects a ticket priority. agents/ticket-priority.agent.abl
Variable sources:
  • priority is a GATHER field. The customer supplies it.
  • COMPLETE reads it in the condition and in the reply.
“HIGH” is stored as 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_ref with type or options. The compiler reports GATHER_ENTITY_REF_CONFLICT.
  • Do not leave options out of a type: enum field. 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
Variable sources:
  • All variables are GATHER fields. The customer supplies each one.
  • plan takes its values and synonyms from the plan_tier entity.
“premium” is stored as 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.
The model reads the customer’s words and returns an option. The runtime accepts that only when the customer’s words are the option itself or one of its synonyms. Any other mapping is rejected, unless the field has an 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 a FLOW step with REASONING: false, a rejected value gets a fixed reason, then the prompt. agents/laptop-support.agent.abl
The default reason is “That isn’t one of the available options.” Change it with a MESSAGES entry.

Reuse values across agents

Declare the values once in ENTITIES 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

Add list: 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 FLOW step with REASONING: false, the customer hears the gather_invalid_option reason, 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_resolution event shows each value with valid and 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_hints entry.

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 prompt that names the options.
  • Synonyms cover the words customers use for each option.
  • Each FLOW step with an enum has a MESSAGES override 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.

Common mistakes

Troubleshooting