> 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

Policies are condition → action rules matched against every turn. They encode safety, compliance, tone, and business rules that apply across all routines.

> **Context** — Policies are one of the two behavioural building blocks of an agent (the other is [routines](https://docs.interactive.ai/agents/concepts/routines.md)). This page defines the model; [Authoring policies](https://docs.interactive.ai/agents/guides/authoring-policies.md) covers how to write good ones.
>
> 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).

## 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 or [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library) | yes      | —                  | Natural-language condition the matcher evaluates each turn. Required even with `always_match: true`.                                                                                                                                                                                                                                                                                                                                                                                          |
| `action`           | string or [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library) | 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](https://docs.interactive.ai/agents/concepts/priorities.md).                                                                                                                                                                                                                                       |
| `always_match`     | boolean                                                                                                                   | no       | `false`            | Skip the matcher; the policy applies on every turn.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `continuous`       | boolean                                                                                                                   | no       | `false`            | The policy stays in force on every turn instead of retiring once its action has been carried out — tone and language rules, standing prohibitions ("never quote opening hours").                                                                                                                                                                                                                                                                                                              |
| `agent_intention`  | boolean                                                                                                                   | no       | `false`            | The condition describes the agent's own likely next move rather than something already said ("You are likely to explain the terms"); the matcher then judges it against the reply being drafted. Word the condition that way.                                                                                                                                                                                                                                                                 |
| `awaits_customer`  | boolean                                                                                                                   | no       | `false`            | The action is complete only once the customer has responded ("ask for the account number"); the engine keeps the policy in play until they do.                                                                                                                                                                                                                                                                                                                                                |
| `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) this policy runs every time it is selected (`service:tool` form). The `condition` is the only gate, so state there when the tools should run.                                                                                                                                                                                                                                                                                                                                      |
| `tool_instruction` | string or [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library) | no       | —                  | Guidance for filling the tools' arguments, alongside `action`. Requires `tools`.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `tool_arguments`   | object                                                                                                                    | no       | —                  | Where each argument comes from (`literal`, `variable`, `input`, or `llm` with instructions), keyed by tool then parameter — the sources [routine tool nodes](https://docs.interactive.ai/agents/guides/authoring-routines.md#arguments) use, except `step_output`: a policy is not a step. `input` is only available to policies scoped to an autonomous routine, and `message` to policies scoped to a conversational routine. A policy can't bind `built-in:emit_output`. Requires `tools`. |
| `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](https://docs.interactive.ai/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](https://docs.interactive.ai/agents/concepts/tools.md#reevaluation-tools).)

## Prerequisites

Policies do not declare a prerequisite guard in their content. To withhold a policy from matching until a tool has run, declare the guard on the agent under `context.relationships.requires` — see [Prerequisites](https://docs.interactive.ai/agents/concepts/priorities.md#prerequisites-requires). Guard the owning routine when you want every routine-scoped policy gated too; scoped policies themselves cannot carry a guard.

## 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](https://docs.interactive.ai/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](https://docs.interactive.ai/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](https://docs.interactive.ai/agents/operations/versioning.md).

## See also

* [Authoring policies](https://docs.interactive.ai/agents/guides/authoring-policies.md) — patterns and anti-patterns
* [Priorities](https://docs.interactive.ai/agents/concepts/priorities.md) — resolving conflicts between policies and routines
* [Conversation lifecycle](https://docs.interactive.ai/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 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/policies.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.
