Skip to main content
Back to how-to guides Add a 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 field type 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
Variable sources:
  • applicant_age and loan_amount are GATHER fields. The customer supplies both.
  • The CONSTRAINTS conditions read both fields. COMPLETE reads both.
Results:

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. Unless ON_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
Variable sources:
  • order_id, refund_amount, and customer_tier are GATHER fields. The customer supplies each one.
  • issue_refund is defined in this file. It reads order_id and refund_amount when the model calls it.
How each rule behaves: 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.
The phase label 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 a FLOW, 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 with BEFORE 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
This rule blocks the tool call. Blocking tool calls is the subject of Block tool calls when required data is missing.

Constraints on a supervisor

A SUPERVISOR 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

A REASONING: 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_check event for each rule, with passed set to true or false and the onFail action.
  • A constraint_guard_skipped event when a rule waits for data that is not yet collected.
  • A constraint_warning event for a broken WARN rule.
  • A constraint_repeat_limit event when MAX_REPEATS runs out.

Production readiness checklist

  • Every REQUIRE, LIMIT, and RESTRICT has an ON_FAIL with customer-facing text.
  • Numeric bounds are constraints, not validate: rules.
  • HANDOFF targets and GOTO steps 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 CLEAR with COLLECT or GOTO.
  • A loop has a limit: MAX_REPEATS with ON_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 GATHER field names exactly.

Common mistakes

Troubleshooting