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). This page defines the model; Authoring policies 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.

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:

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.
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 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.)

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

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

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.

See also

• Authoring policies — patterns and anti-patterns

• Priorities — resolving conflicts between policies and routines

• Conversation lifecycle — when matching runs