Skip to main content
Back to how-to guides Add validate: "<regex>" to a text GATHER field to accept only values that match. Add extraction_pattern to pull the value out of a longer sentence first.

Concept

ABL has two regex settings. They do different jobs. Use validate: for formats that a field type cannot express, such as an order number or a ZIP code. Use extraction_pattern when customers wrap the value in words, such as “my order is AB123456, please check”. Three rules decide whether a pattern works:
  • A validate: pattern matches anywhere in the value. [A-Z]{2}[0-9]{6} accepts “xx AB123456 yy”. Anchor with ^ and $ to require the whole value.
  • Patterns run on a safe engine. Lookahead (?=, lookbehind, and backreferences such as \1 are not supported. Nested quantifiers such as (a+)+ are rejected.
  • Patterns test text only. On an integer, number, or boolean field, the stored value is not text, so the rule always fails. Put the rule on a string field.

Minimal working example

An order-status agent accepts an order number of two capital letters and six digits, and a US ZIP code. agents/order-status-intake.agent.abl
Variable sources:
  • order_number and zip_code are GATHER fields. The customer supplies both.
  • COMPLETE reads both in its condition and reply.
  • This agent stops at a confirmation message. A real agent passes the two values to a lookup tool that you define in your project.
Write the regex with single backslashes, such as \d. ABL does not unescape the text between the quotes.

How it works

  1. The customer replies. The runtime extracts a value for the field.
  2. The runtime applies the field type. A string accepts any text.
  3. The runtime tests the value against validate:.
  4. A match stores the value. No match drops the value, and the field stays missing.
  5. The agent asks again. retry_prompt is the re-ask text for the field. max_retries counts failures for that field and records a validation_max_retries trace event when the limit is reached.
At compile time the compiler checks every pattern: Matching is case-sensitive. Add (?i) at the start for a case-insensitive match. A value with a trailing newline does not match a pattern that ends in $. validation_process: REGEX is the default for a validate: rule. You can omit it. validation_process: LLM replaces the regex with a model judgment and is not covered here.

Common variations

Pull the value out of a sentence

Set extraction_pattern and strategy: pattern. The runtime then finds the value with your regex alone, with no model call. Keep validate: as the final gate. agents/ticket-lookup.agent.abl
“It is TKT-123456, thanks” fills ticket_id with TKT-123456. “tkt-123456” does not match, because the extraction pattern is case-sensitive. strategy: accepts auto, ml, llm, hybrid, and pattern. Any other word is compile error E170. hybrid is an old name for auto.

Capture one part of a match

Wrap the part you want in parentheses and set extraction_group to its number. Group 0 is the whole match and is the default. A group number the pattern does not have falls back to the whole match. This is a section snippet.
“ticket number: TKT-123456” fills the field with TKT-123456. A bare “TKT-123456” does not match, because this pattern requires the words before it.

Share a pattern across fields with ENTITIES

Declare the pattern once in ENTITIES and point fields at it with entity_ref. The entity PATTERN is used as the field’s extraction pattern. It does not reject values by itself, so keep validate: on the field. This is a section snippet.

Hide the value

Set sensitive: true on a field that holds personal data. Rejection messages and traces then leave out the value. See Collect sensitive or PII fields safely.

Verification

Send these messages in a test session, then open the trace. Check in the trace:
  • The extracted candidate for the field, with the stage pattern.
  • The validation error for a rejected value.
  • The stored value in the session data.

Production readiness checklist

  • Every validate: pattern starts with ^ and ends with $, unless a partial match is intended.
  • Rules sit on string fields only.
  • Each pattern was tested with a good value, a wrong-case value, a too-long value, and a value with extra words.
  • Every field with validate: also has a retry_prompt that shows an example of a good value.
  • You chose what happens after max_retries: escalation, a handoff, or a graceful end.
  • Patterns with extraction_pattern and validate: agree on case.
  • Fields with personal data set sensitive: true.
  • Downstream tools accept the format you validate.

Common mistakes

Troubleshooting