CONSTRAINTS section to an agent to enforce rules that a field type cannot express, such as “age 18 or older”, “refund at most 200”, or “no more than 8 seats”. The runtime checks each rule against collected data and runs your ON_FAIL action when a rule breaks.
Concept
A fieldtype checks the format of one value. A constraint checks a business rule over one or more values. Use a constraint when the rule is a number range, a comparison between fields, or a limit that depends on another field.
validate: on a GATHER field does not check numeric bounds. The compiler reads validate: text as a regular expression or enum(...). validate: min(18) rejects every value. Write bounds as a constraint.
A constraint has four parts:
The runtime does not check a rule until the data it reads exists. The compiler adds an
IS NOT SET guard for each field in the condition. A rule on loan_amount is skipped until the customer gives an amount. A rule that already contains IS SET or IS NOT SET is left as you wrote it. A condition made only of OR terms gets no guard.
Minimal working example
A loan agent collects an age and an amount. It enforces an age floor and an amount range.agents/loan-intake.agent.abl
applicant_ageandloan_amountareGATHERfields. The customer supplies both.- The
CONSTRAINTSconditions read both fields.COMPLETEreads both.
How it works
When a rule runs depends on where it is in the agent.
All rules run every turn. Rules do not run in phases.
What happens when a rule breaks
The value that broke the rule stays stored. UnlessON_FAIL clears it, the rule fails again at the next check. Use CLEAR with COLLECT to remove the value and ask again.
A
REQUIRE with no ON_FAIL compiles with an empty message. The rule still blocks, and the customer hears nothing. Always write ON_FAIL.
Realistic example
A refund agent limits standard-tier refunds to 200 before it calls the refund tool. It warns on large amounts and escalates one premium case.agents/refund-agent.agent.abl
order_id,refund_amount, andcustomer_tierareGATHERfields. The customer supplies each one.issue_refundis defined in this file. It readsorder_idandrefund_amountwhen the model calls it.
Write
BEFORE before WHEN on one line. The reverse order fails to compile with INVALID_CEL_SYNTAX. A WHEN: on its own line also works.
Common variations
Scope a rule with WHEN or IMPLIES
WHEN applies a rule only when its condition is true. IMPLIES writes the same rule as one expression. Both lower to the same check. This is a section snippet.
always: is optional. Any other label, such as pre_booking:, only names the group. The compiler reports W823 because the label has no effect on when rules run.
Return to a flow step
In aFLOW, use GOTO to send the customer back to the step that collects the value.
agents/seat-booking.agent.abl
{{_abl_constraint_fail_count}} is the number of times this rule has failed, starting at 1. A flow stops a goto loop after three returns to the same step and escalates.
Check the arguments of a tool call
A rule scoped withBEFORE calling <tool> can read the call’s arguments as tool_args. Set guardrail_builtins: true in EXECUTION first. Without it, the rule cannot read tool_args, fails, and refuses the call. The compiler warns with GUARDRAIL_BUILTIN_NOT_BOUND.
agents/payout-agent.agent.abl
Constraints on a supervisor
ASUPERVISOR accepts a CONSTRAINTS section. A supervisor has no GATHER fields, so a rule that reads a worker’s field compiles with UNDEFINED_CONDITION_VAR. Put the rule on the agent that collects the data.
Step-level notes
AREASONING: true step accepts STEP_CONSTRAINTS lines. They are plain text. The runtime does not evaluate them as rules. Put enforceable rules in CONSTRAINTS.
Verification
Test each rule at its boundary. Send the messages in a test session, then open the trace.
What to check in the trace:
- A
constraint_checkevent for each rule, withpassedset to true or false and theonFailaction. - A
constraint_guard_skippedevent when a rule waits for data that is not yet collected. - A
constraint_warningevent for a brokenWARNrule. - A
constraint_repeat_limitevent whenMAX_REPEATSruns out.
Production readiness checklist
- Every
REQUIRE,LIMIT, andRESTRICThas anON_FAILwith customer-facing text. - Numeric bounds are constraints, not
validate:rules. HANDOFFtargets andGOTOsteps exist in the project.- A rule that must stop a tool call uses
BEFORE calling <tool>. - A rule on a value that the customer can correct uses
CLEARwithCOLLECTorGOTO. - A loop has a limit:
MAX_REPEATSwithON_EXHAUSTED, or an escalation path. - You tested each boundary: below, at, and above the limit. You also tested the unset case.
- Field names in conditions match
GATHERfield names exactly.