Skip to main content
Back to how-to guides Add a REQUIRE ... BEFORE calling <tool> constraint to stop a tool from running until the data it needs is present and valid. The tool does not run. The customer sees the line you wrote in ON_FAIL.

Concept

A model decides when to call a tool. A constraint decides whether the call may go ahead. The runtime checks every constraint that targets a tool, at the moment of the call, and before the tool runs. Four mechanisms can stop a tool call. They differ in who writes the rule and what the customer hears. Use a constraint when the rule depends on agent state, such as gathered fields or session values. Use process.before.require when the rule is about the tool’s own inputs and must travel with the tool. Use confirm: when the customer must approve a side effect. A rejected call is not a retry loop. When a constraint blocks a tool, the turn ends with your ON_FAIL message. The model does not get a chance to reword it.

Minimal working example

A refund agent must not call issue_refund until it has the order number, the amount, and the customer’s confirmation. Refunds above 500 go to a person. issue_refund is a project-local tool. Replace it with your refund API. agents/refund-agent.agent.abl
Variable sources:
  • order_id, amount, and refund_confirmed are GATHER fields. The customer supplies them.
  • The tool inputs order_id and amount come from the model, which reads the gathered fields.
  • issue_refund is a project-local assumption. Its backing API must exist in your project.

How it works

BEFORE calling issue_refund ties the rule to one tool. The compiler turns the rule into “if this is a call to issue_refund, then the condition must hold”. The rule is skipped for every other tool and for every other point in the conversation. When the model calls issue_refund, the runtime evaluates each matching rule against the current session. The first rule that fails decides the outcome. Three details matter:
  • IS SET tests that a value exists. A rule on a field that is not yet gathered fails at the tool call. It does not wait for the field.
  • Rules are not checked “once per turn”. They are checked at each call. A blocked call can succeed on the next turn after the customer supplies the data.
  • A WARN rule never blocks. It records a warning and the call goes ahead.

What the customer hears

The ON_FAIL form decides the reply. An ESCALATE "text" with quotes keeps a stray opening quote in the reason. Write ESCALATE text.

Common variations

Collect the missing data, then escalate after repeated failures

Use the block form to send the customer back to collection. Cap the loop with MAX_REPEATS. agents/account-change-agent.agent.abl
Variable sources:
  • account_id, new_email, region, and vip_override are GATHER fields.
  • tool_args holds the arguments of the pending call. It exists only at a BEFORE calling check, and only when EXECUTION: guardrail_builtins: true is set.
What each rule does: The first rule answers two failures with a collection prompt. On the third failure, ON_EXHAUSTED escalates. The ON_EXHAUSTED count is per conversation. Without guardrail_builtins: true, tool_args is not bound. A rule that reads it fails, so the tool is refused on every call. The compiler warns with GUARDRAIL_BUILTIN_NOT_BOUND.

Block a FLOW CALL step

The same rule gates a CALL step in a FLOW. A block can send the flow to an earlier step with GOTO. agents/order-cancellation.agent.abl
Variable sources:
  • order_id and cancel_confirmed are gathered in collect_details.
  • cancel_result is the output of the cancel_order call. The done step reads its status.
A FLOW step has two more guards on a CALL. If a required tool input is empty, the platform does not run the tool. It asks the customer for the missing fields, or reports the tool as not run when it cannot ask. In a PARALLEL block, a blocked call fails that one call and nothing else.

Put the rule on the tool

Use process.before.require when the check is about the tool’s own inputs. Read the inputs with params.<name>. Session values are also readable by name.
on_fail takes one of these:

Require confirmation before a side effect

confirm: makes the runtime ask before the tool runs. The compiler warns with SIDE_EFFECT_TOOL_WITHOUT_CONFIRMATION when a side-effecting tool sets none. The default question reads “Please confirm before I go ahead”, followed by the call details and “Shall I proceed?”. Override it with the tool_confirmation_request message. immutable: locks the listed inputs after the customer approves, so the model cannot change them. A confirmation expires after five minutes.

Hold every tool until required fields are collected

EXECUTION: inline_gather: true blocks every domain tool until all required GATHER fields have a value. The model gets a GATHER_INCOMPLETE error that lists the missing fields. It collects them and tries again. This is a section snippet.

Verification

Send these turns to the agent in a test session and open the session trace. What to check in the trace:
  • A constraint_check event for each rule that applies at the tool call. A failed one names the rule.
  • A blocked call has a failed constraint_check and no result from the tool.
  • For process.before, a process_before_require event shows the result.
  • For a FLOW step, the trace shows the step ending on the block, or the jump to the GOTO step.

Production readiness checklist

  • Every tool named in a BEFORE calling rule exists in TOOLS. A misspelled tool name never matches, so the rule never fires.
  • Every BEFORE target uses the form calling <tool> or tool <tool>. Other forms compile with warning W824 and do nothing.
  • Each blocking rule has an ON_FAIL that the customer can act on.
  • Each side-effecting tool sets confirm: on purpose.
  • Rules that read tool_args run with guardrail_builtins: true.
  • You tested the block, the pass, a different tool, and a repeated block for each rule.
  • There is an escalation path for a customer who cannot supply the data. Use MAX_REPEATS with ON_EXHAUSTED, or a COMPLETE or handoff rule.
  • Trace alerts cover blocked calls on tools that change money, access, or records.

Common mistakes

Troubleshooting