Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%

Which rule wins: priority

Priority is the number on a rule that decides order: the evaluator sorts every rule by priority from high to low and takes the first one that matches, so when two rules match the same call, the higher priority wins.

Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0

The Policy conditions and a missing field lesson matched one rule at a time. Real policies have rules that overlap, where a broad allow and a narrow deny both match the same call. Priority is how you say which one decides.

Two rules that both match a refund

This file has an allow rule and a deny rule, and both have a condition that matches a refund. The allow rule carries the higher priority, so it is checked first and wins.

yaml
version: "1.0"
name: refund-priority
rules:
  - name: allow-refunds
    condition: {field: action, operator: eq, value: refund}
    action: allow
    priority: 20
  - name: deny-refunds
    condition: {field: action, operator: eq, value: refund}
    action: deny
    priority: 10
defaults:
  action: deny
ExampleThe higher-priority allow rule decides
import warnings; warnings.simplefilter("ignore")
from agent_os.policies.schema import PolicyDocument
from agent_os.policies.evaluator import PolicyEvaluator

doc = PolicyDocument.from_yaml("priority.yaml")
d = PolicyEvaluator(policies=[doc]).evaluate({"action": "refund"})

# both rules match; the evaluator takes the highest priority first
print("winner:", d.matched_rule, "| allowed:", d.allowed)

Raising the deny rule above the allow

Nothing about the conditions changes. Raising deny-refunds above allow-refunds is enough to flip the verdict, because the evaluator now reaches the deny rule first.

ExampleA higher number on the deny rule flips the verdict
# raise the deny rule above the allow rule; the conditions are untouched
rules = {r.name: r for r in doc.rules}
rules["deny-refunds"].priority = 30

d = PolicyEvaluator(policies=[doc]).evaluate({"action": "refund"})
print("winner:", d.matched_rule, "| allowed:", d.allowed)

What the priority number did

  • Both rules matched the refund in each run, so the condition is not what chose the winner.
  • The first rule in priority order won, high to low, and the evaluator stopped at it without looking further.
  • Flipping one number flipped the decision, from allowed to denied, with the two conditions left exactly as they were.

How the order is decided

Priority
Default when you omit it0
SortedHighest first
The winnerThe first matching rule in that order
A tie on priorityThe earlier rule in the file is checked first

Where priority matters

  • A broad allow with a narrow exception, where a high-priority deny carves one tool out of a general allow.
  • A deny you never want overruled, given the top priority so nothing checked later can allow it.
  • A staged rollout, where a temporary high-priority rule sits above the permanent set and is removed later.
Watch out. A deny you rely on can be defeated by an allow with a higher priority that matches the same call, and the evaluator warns you about neither the overlap nor the shadowed rule. Give a deny you must not lose the highest priority, and read the matched_rule on a decision to see which rule fired.
Try it yourself
  • Give both rules the same priority and see which one wins, then swap their order in the file.
  • Remove the priority line from both rules and confirm they default to 0 and the file order decides.
  • Add a third rule with priority 100 that denies every action and watch it shadow the rest.

Little by little, you're building something great.