Priorities, entailments & prerequisites
Relationship declarations between routines and policies: priorities resolve conflicts, entailments chain policy activations, and requires keeps entities dormant until a tool has run. Without them, eve
Context — When several policies match and a routine is mid-flow on the same turn, something has to win. This page covers the default behaviour and the three explicit relationship mechanisms under
context.relationships: priorities (who wins), entailments (what else applies), and requires (what stays dormant until a tool has run).YAML examples follow manifest schema 9.10.0. Manifest and content shapes are schema-versioned and differ across runtime versions — see Versioning & compatibility.
Default: everything is equal
With no priority configuration, all matched policies and the active routine have equal standing. The engine weighs them together — policy criticality (LOW/MEDIUM/HIGH) influences emphasis, but nothing categorically outranks anything else. For most agents this is fine: well-written policies and routines rarely conflict.
You need explicit priorities when conflicts are by design:
A safety policy must override any routine that would continue the flow ("the customer mentioned self-harm" beats "continue the booking flow").
Two routines can both plausibly activate and one should win (a dedicated escalation routine over a generic FAQ routine).
A compliance policy must beat a softer formatting policy.
Declaring priorities
Priorities live in the manifest under context.relationships:
agent_config:
context:
relationships:
priorities:
# 1. A policy that beats every routine
- higher: policy:self-exclusion-safety
over_all_routines: true
# 2. A policy that beats specific targets (routines and/or policies)
- higher: policy:rg-permanent-safety
over:
- routine:account-reactivation
- policy:email-format
# 3. A routine that beats another routine
- higher: routine:priority-path
over:
- routine:fallback-pathEntry fields
higher
string
The reference that wins. Form: routine:<id> or policy:<id>.
over
list of strings
The references higher outranks (same routine:/policy: form). Mutually exclusive with over_all_routines.
over_all_routines
true
higher outranks every routine in the manifest. It does not outrank any policy, even when higher is itself a policy. Mutually exclusive with over.
Exactly one of over / over_all_routines is required per entry (the schema enforces this). Ids must match routines/policies actually referenced in the manifest.
Semantics
A priority is a pairwise relation:
higherbeats each listed target. Pairs not covered by any entry remain equal-priority.Priorities are not transitive chains you must spell out — but they are also not inferred. If A must beat C, say so; A-beats-B plus B-beats-C does not imply it.
A priority is a hard block, not a tiebreak. When the
higherentity matches, each of itsovertargets is deactivated for that turn — it does not fire, even if it also matched, and even if it does not conflict with the winner. No instruction conflict is required to suppress the loser.over_all_routines: trueis the standard pattern for safety policies: whatever flow is mid-flight, the safety action takes precedence and the active routine is suppressed for that turn. The routine's position is preserved, so it resumes on the next turn where the safety policy no longer matches — suppressed per turn, not permanently torn down.
Worked example
DriveAway adds an incident-safety policy that must beat the booking flow:
Mid-booking, the customer mentions they were just in an accident with a rental. incident-handoff matches; because it outranks all routines, the agent follows its action (express concern, hand off to a human) instead of pressing on with "and what's the driver's age?". Next turn, if the incident topic has passed, book-a-car resumes where it left off.
When you want a prerequisite, not a priority
A priority only decides who wins among things that matched. It is the wrong tool for "this must happen before anything else can". Giving an authentication policy over_all_routines: true still lets every routine match and activate; the auth policy merely outranks them once it also matches, and it goes on outranking them after authentication succeeds. Use requires: instead — see below.
Prerequisites (requires:)
requires: is declared once per agent under context.relationships. While a guard is unsatisfied the covered routines and policies are not evaluated at all: no matcher call, no match, no activation. Chat agents that authenticate via a tool declare it; email agents that arrive already authenticated omit it. Both can pin the same routine content.
Entry fields
tool
string
Tool that must have run successfully. Bare name or service:tool.
result_has
string or mapping
Optional. A key name must be present and non-empty; a mapping requires every named key to equal the given value. Omit to require only a clean run (no protocol error).
all_routines
true
Guard every routine pinned on this agent (not policies). Mutually exclusive with on.
on
list of routine:<id> / policy:<id>
Explicit coverage. Mutually exclusive with all_routines.
excludes
list of routine:<id>
Optional. Routines left unguarded when all_routines is set. Invalid with on.
Exactly one of on / all_routines is required per entry. Policies are never covered by all_routines — name them under on. Use excludes when most routines need the guard but a couple (e.g. greet / public FAQ) must run before authentication.
Checked every iteration, satisfied for the rest of the session. The guard is derived from the session's tool events each time the engine prepares a response, never cached. A tool that succeeds mid-turn opens the guard on the next preparation iteration of that same turn. Because tool events stay in the session, a satisfied guard stays satisfied.
Boot checks. The server resolves tool at startup and refuses to boot on an unknown or ambiguous name, on a reference the manifest does not pin, or on an entity covered by more than one entry. A misspelled result_has key is not checked at boot — it shows up as a guard that never opens. Guarding an autonomous routine fails boot (a fresh session could never open the guard); use on and omit autonomous routines when the agent pins any.
Routine and policy content do not accept requires:. Guard the owning routine instead of a routine-scoped policy.
Entailments
An entailment chains policy activations: whenever the when policy matches, every policy in also_apply is activated too — without its own condition having to match. Policy→policy only (routines cannot participate):
when
string (policy:<id>)
Source policy whose match pulls in the targets.
also_apply
list of policy:<id> (≥ 1)
Policies activated whenever when matches.
Use entailments to keep condition text DRY: instead of copying "the customer mentioned self-exclusion" into the tone policy and the no-retention-offers policy, write the trigger once and entail the companions. Referenced ids may be top-level or routine-scoped policies (referenced by id) — a routine-scoped id resolves the same as a top-level one, provided each id is globally unique.
See also
Policies —
criticalityand matchingRoutines — activation conditions
Policies — matching and criticality
Manifest & content schemas — full field reference
Last updated
Was this helpful?

