> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/concepts/priorities.md).

# 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](https://docs.interactive.ai/agents/concepts/policies.md) match and a [routine](https://docs.interactive.ai/agents/concepts/routines.md) 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 1.4.0**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](https://docs.interactive.ai/agents/operations/versioning.md).

## 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`:

```yaml
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-path
```

### Entry fields

| Field               | Type            | Meaning                                                                                                                                                         |
| ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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**: `higher` beats 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 `higher` entity matches, each of its `over` targets 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: true` is 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:

```yaml
agent_config:
  context:
    policies:
      - id: incident-handoff
        version: 1
    routines:
      - id: book-a-car
        version: 1
    relationships:
      priorities:
        - higher: policy:incident-handoff
          over_all_routines: true
```

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.

```yaml
agent_config:
  context:
    relationships:
      requires:
        - tool: integration:authenticate_customer
          result_has: player_info
          all_routines: true
```

```yaml
# all routines except a couple that must run before auth
relationships:
  requires:
    - tool: integration:authenticate_customer
      result_has: player_info
      all_routines: true
      excludes: [routine:greet, routine:public-faq]
```

```yaml
# narrower scope — name routines and policies explicitly
relationships:
  requires:
    - tool: integration:authenticate_customer
      result_has: player_info
      on: [routine:withdrawals, routine:bonus, policy:report-balance]
```

### Entry fields

| Field          | Type                                   | Meaning                                                                                                                                                                |
| -------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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):

```yaml
agent_config:
  context:
    relationships:
      entailments:
        - when: policy:self-exclusion-request
          also_apply:
            - policy:rg-tone
            - policy:no-retention-offers
```

| Field        | Type                        | Meaning                                         |
| ------------ | --------------------------- | ----------------------------------------------- |
| `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](https://docs.interactive.ai/agents/concepts/policies.md) — `criticality` and matching
* [Routines](https://docs.interactive.ai/agents/concepts/routines.md) — activation conditions
* [Policies](https://docs.interactive.ai/agents/concepts/policies.md) — matching and criticality
* [Manifest & content schemas](https://docs.interactive.ai/agents/reference/manifest.md) — full field reference


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/agents/concepts/priorities.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
