> 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/policies.md).

# Policies

> **Context** — Policies are one of the two behavioural building blocks of an agent (the other is [routines](/agents/concepts/routines.md)). This page defines the model; [Authoring policies](/agents/guides/authoring-policies.md) covers how to write good ones.
>
> YAML examples follow **manifest schema 6.1.5**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](/agents/operations/versioning.md).

## What a policy is

A policy is a standalone **condition → action** pair, written in natural language, stored as a versioned YAML document in the platform catalog and referenced from the manifest:

```yaml
id: minimum-driver-age
name: Enforce Minimum Driver Age
condition: >
  The user mentions a driver who is under 21 years old, or asks whether
  someone under 21 can rent.
action: >
  State plainly that the minimum driver age at DriveAway is 21, so the
  booking cannot proceed for that driver. If there is another adult in
  the party who is 21 or older, offer to book under that person's name
  instead. Do not invoke the booking tool with an under-age driver.
criticality: HIGH
```

On every turn, the **policy matcher** evaluates each policy's `condition` against the conversation (in batches of `policy_batch_size`, default 5, per evaluation-model call). When a condition matches, the policy's `action` becomes a binding instruction for the rest of the turn — layered on top of whatever routine is active.

## Fields

| Field              | Type                        | Required | Default            | Meaning                                                                                                                                                                                                                         |
| ------------------ | --------------------------- | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | string                      | yes      | —                  | Stable identifier the engine keys the policy on. For stored policies it matches the catalog name the document is published under (what the manifest's `context.policies[].id` references).                                      |
| `condition`        | string                      | yes      | —                  | Natural-language condition the matcher evaluates each turn. Required even with `always_match: true`.                                                                                                                            |
| `action`           | string                      | no       | —                  | What the agent must do when the condition matches. May include both tool usage and customer-facing messaging. Omit for an **observation** — a condition-only policy whose match informs the turn without prescribing an action. |
| `name`             | string                      | no       | falls back to `id` | Display label for the platform UI. Cosmetic — not used for matching.                                                                                                                                                            |
| `description`      | string                      | no       | —                  | Free-form rationale shown to operators; not used for matching.                                                                                                                                                                  |
| `criticality`      | `LOW` \| `MEDIUM` \| `HIGH` | no       | `MEDIUM`           | How strictly a matched policy is enforced. `HIGH`/`MEDIUM` are mandatory instructions; `LOW` is soft guidance the agent may deprioritise. Does **not** resolve conflicts — see [priorities](/agents/concepts/priorities.md).    |
| `always_match`     | boolean                     | no       | `false`            | Skip the matcher; the policy applies on every turn.                                                                                                                                                                             |
| `track`            | boolean                     | no       | `true`             | When `true`, a policy that has already applied is re-matched on later turns with a lighter "previously-applied" check instead of full matching. Set `false` to force full matching every turn.                                  |
| `tools`            | list of strings             | no       | —                  | Tool id(s) the agent may call when this policy applies (`service:tool` form).                                                                                                                                                   |
| `reevaluate_after` | list of strings             | no       | —                  | Tool id(s) whose execution re-triggers this policy's matching (see below).                                                                                                                                                      |
| `metadata`         | object                      | no       | —                  | Arbitrary key/values attached to the policy (e.g. `severity`, `category`); merged with server-derived keys.                                                                                                                     |

Machine-validated rules (the published JSON Schema enforces these): `id` and `condition` required; unknown fields rejected.

## Policies vs routines

The single most important distinction in the configuration model:

|               | Policy                                                                                | Routine                                                                 |
| ------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Shape         | One condition → one action                                                            | Multi-node graph                                                        |
| State         | None — re-matched fresh every turn                                                    | Tracks the current node across turns                                    |
| Tool + speech | One `action` may both call a tool and speak — the model handles both in a single turn | Strictly separated: a node either calls tools **or** speaks, never both |
| Use for       | Cross-cutting rules: safety, compliance, tone, escalation triggers                    | Structured flows: collect → fetch → branch → respond                    |

If you find yourself writing a policy whose action is a sequence ("first ask X, then call Y, then confirm Z"), it should be a routine. If you find yourself adding the same guard node to every routine, it should be a policy.

## How matching behaves

* **Per-turn, stateless.** A policy that matched last turn has no special status this turn; the matcher re-reads the conversation.
* **Multiple policies can match simultaneously.** All matched actions are in force for the turn. When they pull in different directions, only an explicit [priority](/agents/concepts/priorities.md) resolves which wins — `criticality` does not (see below).
* **`always_match: true`** is for rules that must never depend on a model's judgement of relevance — e.g. regulatory disclaimers, hard prohibitions. Use sparingly: every always-on policy consumes prompt space in every turn.
* **`reevaluate_after`** re-runs this policy's match after the listed tool executes — whether it succeeds or errors — instead of relying on the match made at the start of the turn. Example: an authentication policy stops matching once `crm:authenticate_customer` has run — listing that tool in `reevaluate_after` makes the engine re-check as soon as the call lands. (The manifest-level `context.reevaluation_tools` is the same mechanism with routine-wide scope — see [Reevaluation tools](/agents/concepts/tools.md#reevaluation-tools).)

## Criticality: how strictly a policy is enforced

`criticality` controls **how a matched policy is presented to the model** — not how conflicts are resolved, and not how hard the policy is matched:

| Level              | How a matched policy is treated                                                                                         | Use for                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `HIGH`             | Rendered as a mandatory instruction the agent must follow.                                                              | Safety, compliance, money, hard prohibitions.                                |
| `MEDIUM` (default) | Rendered as a mandatory instruction the agent must follow.                                                              | The bulk of behavioural rules.                                               |
| `LOW`              | Rendered as a soft "general principle"; the prompt tells the model to prioritise context-specific instructions over it. | Tone nudges and optional suggestions where an occasional miss is acceptable. |

Two things to know:

* **`HIGH` and `MEDIUM` behave identically today.** Both are matched every turn and enforced as mandatory instructions; the level is an authoring signal — and reserved for future weighting — not a current behavioural difference. Reach for `HIGH` on the rules whose importance you want to make explicit: safety, compliance, hard prohibitions.
* **`LOW` is the only level the agent may quietly skip.** A `LOW` policy is matched the same way but rendered as optional guidance, so the model is free to deprioritise it. Use it only where a miss is acceptable.

Criticality does **not** affect matching cost or conflict resolution. Every in-scope policy is matched each turn in batches of `policy_batch_size` regardless of level, so per-turn cost scales with the number of policies, not their criticality. And when two matched policies conflict, only an explicit [priority](/agents/concepts/priorities.md) decides which wins — a `HIGH` policy still needs a priority entry to categorically override a routine or another policy.

## Scoping: agent-wide vs routine-scoped

Policies referenced in the manifest's `context.policies` apply agent-wide. A routine can additionally declare its own `policies:` list — policies with the same field shape (an explicit `id` is required), active **only while that routine is active**:

```yaml
# inside a routine document
policies:
  - id: billing-check
    name: Billing Address Check
    condition: "About to finalize a purchase"
    action: >
      Verify the billing address is correct before proceeding with the
      purchase.
    always_match: true
```

Use routine-scoped policies for rules that only make sense mid-flow; keep genuinely global rules in the manifest list so they hold even when no routine is active. Routine-scoped policies **can** be referenced from the manifest's `relationships:` block ([priorities](/agents/concepts/priorities.md) and entailments) by their `id`, the same as top-level policies — the `id` must be globally unique across top-level and scoped declarations (a collision fails validation at boot).

## Referencing from the manifest

```yaml
agent_config:
  context:
    policies:
      - id: minimum-driver-age
        version: 1
      - id: stay-on-topic
        version: 1
```

Version pins are exact. Publishing a new policy version does nothing until a manifest pinning it is deployed — see [Versioning & compatibility](/agents/operations/versioning.md).

## See also

* [Authoring policies](/agents/guides/authoring-policies.md) — patterns and anti-patterns
* [Priorities](/agents/concepts/priorities.md) — resolving conflicts between policies and routines
* [Conversation lifecycle](/agents/concepts/conversation-lifecycle.md) — when matching runs


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.