Concept
A rejected value is never stored. The field stays missing and the agent asks again. Recovery has three layers. Set each one on purpose.
Without layers 2 and 3, a customer who cannot supply a value is asked again on every turn. Nothing ends the loop unless you set a limit.
For the type reasons the runtime gives by default, see Validate collected fields by type.
Pick the layer
Minimal working example
An agent collects a work email. After two failed attempts, it tells the customer and escalates.agents/work-email-verifier.agent.abl
work_emailis aGATHERfield. The customer supplies it.bookedreadswork_email.
- The
ESCALATEblock routes to your project’s default human-agent connection. Replace the trigger and routing with your own. See When to escalate a conversation to a human.
- The first invalid answer gets “Use an address like name@company.com.” This text replaces the whole re-ask.
- The second invalid answer reaches
max_retries: 2. The agent says theRESPONDline and escalates. - A valid answer at any point stores the email and moves to
booked.
How it works
The re-ask wording
retry_prompt, max_retries, and validation_process need a validate: rule. Without one, validation fails with GATHER_VALIDATION_RULE_REQUIRED.
Reason text and language
The reason comes from the first source that has text for the customer’s language:- The project message catalog.
- The agent
MESSAGESblock. - The built-in English default.
MESSAGES text hears only the field prompt. The English reason is left out on purpose. Add text for every language you support.
An LLM validator reason is shown as written. An LLM validation that fails without a reason uses gather_invalid_value.
The per-field limit
max_retries counts failed validations of one field. The count starts at 1 on the first failure.
Only fields with a
validate: rule are counted. A field with no validate: rule is never counted, even when its type check rejects a value. Use MAX_ATTEMPTS to limit those.
In a top-level GATHER, max_retries only records the count and writes the trace event. No handler runs. Use a FLOW step when the agent must act on the limit.
What the handler can do
AnON_ERROR handler for validation_error takes these actions in a FLOW step.
With no matching handler, the runtime applies the default handler and the step stays active. The customer keeps being asked. The failure count keeps rising, and the handler runs only once.
The per-step limit
MAX_ATTEMPTS counts customer turns that leave a required field of the step missing. A rejected value leaves its field missing, so it counts. When the count reaches the limit, the flow moves to ON_EXHAUSTED. Both settings are needed. With only one, the runtime ignores both.
A FLOW step that asks the customer a question and has neither a max_retries handler nor MAX_ATTEMPTS has no exit.
Common variations
Move to a fallback step after several failed turns
UseMAX_ATTEMPTS when the failure is not tied to one field. The fallback can offer another channel or escalate.
agents/reference-code-collector.agent.abl
reference_codeis aGATHERfield. The customer supplies it.donereadsreference_code.
Override the reason text
Set theMESSAGES keys from Validate collected fields by type. Use gather_invalid_value for rejections that no type key covers.
agents/callback-messages.agent.abl
Model-led recovery in a top-level GATHER
This is a section snippet. The model words the re-ask and sees theretry_prompt as a hint. After three failures the runtime writes the validation_max_retries event. It does not stop the agent.
FLOW step.
Sensitive fields
Asensitive: true field never quotes the rejected value in its reason, in the trace, or in logs. Write retry_prompt text that does not repeat the value either.
Verification
Test in a session and open the trace.
What to check in the trace:
validation_max_retriesshows the field, the failure count, and the limit.agent_error_handledshows thevalidation_errorsubtype, the action, and the field. It appears inFLOWsteps only.flow_step_attempts_exhaustedshows the step, the attempts, and theON_EXHAUSTEDtarget.- The session values
_validation_retriesand_validation_exceededshow per-field counts and exceeded fields.
Production readiness checklist
- Every step that asks for a validated field has an exit: a
max_retrieshandler,MAX_ATTEMPTSwithON_EXHAUSTED, or both. - The exit leads somewhere real. The
ESCALATEblock has routing to a live queue, or the fallback step offers another way forward. retry_prompttells the customer what a good answer looks like. It does not say “invalid”.MESSAGEShas text for every supported language.- Fields that hold personal data are
sensitive: true. - Tests cover one failure then success, repeated failure, a limit that is reached, and a customer who asks for a person.
- Monitoring alerts on
validation_max_retriesandflow_step_attempts_exhausted. A rising count points to a rule that is too strict.