Skip to main content
Back to how-to guides Use this pattern to control what a customer hears after a rejected value, and what the agent does when the customer keeps failing.

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
Variable sources:
  • work_email is a GATHER field. The customer supplies it.
  • booked reads work_email.
Companion resources: What the customer experiences:
  1. The first invalid answer gets “Use an address like name@company.com.” This text replaces the whole re-ask.
  2. The second invalid answer reaches max_retries: 2. The agent says the RESPOND line and escalates.
  3. 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:
  1. The project message catalog.
  2. The agent MESSAGES block.
  3. The built-in English default.
A customer whose language is not English and has no catalog or 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

An ON_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

Use MAX_ATTEMPTS when the failure is not tied to one field. The fallback can offer another channel or escalate. agents/reference-code-collector.agent.abl
Variable sources:
  • reference_code is a GATHER field. The customer supplies it.
  • done reads reference_code.

Override the reason text

Set the MESSAGES 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 the retry_prompt as a hint. After three failures the runtime writes the validation_max_retries event. It does not stop the agent.
To make the agent act on the limit, collect the field in a FLOW step.

Sensitive fields

A sensitive: 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_retries shows the field, the failure count, and the limit.
  • agent_error_handled shows the validation_error subtype, the action, and the field. It appears in FLOW steps only.
  • flow_step_attempts_exhausted shows the step, the attempts, and the ON_EXHAUSTED target.
  • The session values _validation_retries and _validation_exceeded show per-field counts and exceeded fields.

Production readiness checklist

  • Every step that asks for a validated field has an exit: a max_retries handler, MAX_ATTEMPTS with ON_EXHAUSTED, or both.
  • The exit leads somewhere real. The ESCALATE block has routing to a live queue, or the fallback step offers another way forward.
  • retry_prompt tells the customer what a good answer looks like. It does not say “invalid”.
  • MESSAGES has 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_retries and flow_step_attempts_exhausted. A rising count points to a rule that is too strict.

Common mistakes

Troubleshooting