> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies & guardrails: rules your agent must follow

> Write policies that guide the model and guardrails that check what the caller and the agent say, then add them to agents, monitor them and enforce them.

Policies & guardrails are rules you write once and add to any agent in the project. A policy tells the model how to behave. A guardrail checks what the caller says, what the agent is about to say, or both, and acts when it matches: it can replace the line, end the call or run a function. This page covers both, from creating a rule to how it runs on a call.

## Policy or guardrail

| | Policy | Guardrail |
| - | - | - |
| What it is | "An instruction the agent follows while it applies: on every reply, or only when what the caller says fits your description." | "A check on the caller's words, the agent's reply, or both. When it matches it can say a set line, end the call or run a function." |
| Guaranteed | No. "The model understands meaning, so it isn't guaranteed." | Yes, "for what it matches, with no added delay." |
| Use it for | Tone, scope, what to say and not say | Words or patterns that must never get through, actions that must happen |

A guardrail can also carry an instruction, so the model avoids the problem in the first place and the check catches what slips through.

## Before you start

| Action | Owner | Admin | Member |
| - | - | - | - |
| Create and edit policies and guardrails | Yes | Yes | Yes |
| Add them to an agent, turn them on or off | Yes | Yes | Yes |
| Delete them from the library | Yes | Yes | No |

These are the role defaults. An owner can change them per member in [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## Create a rule

Rules live in the project library: open **Policies & guardrails** in the sidebar. "Rules your agents follow and checks they can't skip. Shared across the project's agents." The **Yours** tab lists the project's rules, and **Templates** has ready-made ones.

![The Policies & guardrails page, Yours tab, with two policies and three guardrails, some monitoring and one enforcing](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/safety/policies-list-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=c76a44b27ac7e2d4d537331736649a98)

**1. Click Create**

Pick a blank policy or guardrail, or **From a template**.

![The Create menu with Policy, Guardrail and From a template](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/safety/create-menu-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=017d1db3bf4f773c86882f8e4b507902)

**2. Fill in the fields**

Give it a **Name**, then fill in the numbered sections: **When it applies**, **What it checks** and **What happens** (guardrails only), and **Instruction to the model**. See the field reference below.

![The New guardrail editor checking what the agent says, looking for two phrases, saying a fixed line instead, in Monitor mode](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/safety/new-guardrail-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=2f4e2e8d2637e02bd64165addbad41c1)

**3. Save**

A new guardrail "Saves in monitor mode", so it records when it would fire and changes nothing on calls until you switch it to **Enforce**.

You can also create a rule from inside an agent's settings. It goes into the library and onto that agent.

## Add a rule to an agent

**1. Open the agent's settings**

In a single prompt agent, open the agent's settings panel. In a flow agent, open **Global settings**. Find **Policies & guardrails**: "Rules this agent follows and checks it cannot skip".

**2. Click Add**

Pick a rule **From the library**, start a new one, or **Start from a template**.

**3. Turn it on**

Each rule has a switch. The section shows how many are on, for example "3 of 4 on for this agent". To take a rule off the agent without deleting it, use **Remove from this agent**.

![An agent's Policies & guardrails settings: 3 of 4 on, two policies and two guardrails with their switches, and templates to start from](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/safety/agent-policies-guardrails-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=55ebb0134deb9bffd8586c9dc295255a)

> [!WARNING]
>
> Rules are not part of an agent's version. Adding, removing, switching or editing a rule changes live calls right away, for every version of the agent, with no publish. An edit in the library applies to every agent using it: "Used by \{count} agents. Your changes apply to all of them."

## Field reference

### For policies and guardrails

| Field | What it does | Default |
| - | - | - |
| **Name** | Required, up to 255 characters | |
| **Notes** | Optional. "Why this rule exists, for whoever edits it next." Up to 255 characters. | |
| **When it applies** | **Every turn**, or **Per user response**: only when what the caller says fits your description | **Every turn** |
| **What the user says** | For **Per user response**: "Describe it, quote examples, or both, in any language." Matched by meaning, so the exact words don't matter. Up to 5,000 characters. | |
| **Only when** | Conditions on the call's [variables](https://docs.tryhamsa.com/agents/variables/overview.md). Choose **All** or **Any**. | None |
| **Instruction to the model** | Required. Added to the model's instructions while the rule applies. "Write it in English; the agent still answers in the caller's language." You can use variables in it. | |
| **Severity** | **Normal**, **High** or **Critical**. "Critical rules are placed closest to the model's reply and flagged first in call review." | Policy: **Normal**. Guardrail: **High** |

**Only when** operators: **equals**, **is not**, **contains**, **doesn't contain**, **is more than**, **is less than**, **is set**, **is not set**.

A policy always needs an instruction. Write one for every guardrail too: it helps the model avoid the problem before the check has to act.

### For guardrails only

| Field | What it does | Default |
| - | - | - |
| **What it checks** | **Caller says**: "The caller's words, before the model sees them." **Agent says**: "Each sentence of the agent's reply, before it is spoken." **Both**: each side "with its own check and action". | **Agent says** |
| **Look for** | What makes it fire: **None**, **Words**, **Pattern** or **Function or macro** (see below) | |
| **What happens** | What the guardrail does when it fires (see below) | |
| **Mode** | **Monitor**: "Records when it would fire. Changes nothing on the call." **Enforce**: "Acts on the call whenever it fires." | **Monitor** |

**Look for** options:

| Option | Fires when |
| - | - |
| **None** | Never. "With nothing to look for on any side, the guardrail only applies its instruction, like a policy." |
| **Words** | Any word or phrase in your list appears. Type one and press Enter to add it. |
| **Pattern** | A regular expression matches anywhere in the text, for example `refunds?` for "refund" or "refunds" |
| **Function or macro** | A JavaScript check function returns `true`, or a Jinja check macro renders anything except empty, false, 0, none or no. See [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md). |

**What happens** options:

| Option | What happens |
| - | - |
| **Nothing** | "The match is recorded, and the call carries on as it was." |
| **Message** | "The matching turn or sentence is replaced by your message." Write it under **Say instead**. |
| **Disconnect** | The agent says your goodbye line, if you wrote one, then ends the call. |
| **Function or macro** | It runs and the call carries on. Text it returns replaces what was said; an object (or, for a macro, a JSON object) sets those variables on the call. |

### Try a check before you save

Under **Look for**, **Try it** lets you paste "something a caller or the agent might say" and see whether it would fire. **Checked as:** shows the text the way the check reads it.

## Write checks that match

Checks read a cleaned-up copy of the text: lowercase, with Arabic-Indic digits turned into 0 to 9. So:

* **Words** and **Pattern** ignore the caller's letter case. Write patterns in lowercase: a pattern with capital letters never matches on a call.
* A pattern written for `5` also matches `٥`.
* Named groups, written `(?<name>…)`, and Unicode classes such as `\p{L}` don't work on calls, though they save and work in **Try it**. A pattern that doesn't work on calls never fires.
* A **Function or macro** action gets the text as it was said.

## Templates

**Templates** has ready-made rules in categories: **Speech**, **Safety**, **Privacy**, **Accuracy**, **Conversation**, **Escalation** and **Tools**. For example "Speech-safe output", "No emoji", "AI disclosure", "Stay on topic", "Block attempts to override instructions", "Don't read back full numbers", "Never ask for secrets", "Escalate on request", "Confirm before an action" and "Protect personal data".

![The Templates tab listing ready-made policies and guardrails](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/safety/templates-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=7eba9ab3c487f6fd5a58cebc3b93e1ad)

Open one and click **Use template** to make it your own rule, then edit it. "Protect personal data" also adds two functions; see [Protect personal data](https://docs.tryhamsa.com/agents/safety/personal-data.md).

## How it works on a call

* **Policies and guardrail instructions** are added on each caller turn. **Every turn** rules are always added. **Per user response** rules are added when the caller's words match your description. If that matching takes too long on a turn, only **Every turn** rules apply on that turn.
* **Caller says** checks run on the caller's final words, before the model, the conversation history and [extracted variables](https://docs.tryhamsa.com/agents/variables/extracted-variables.md) see them. So a rewrite (for example masking a phone number) is what the model and the history get.
* **Agent says** checks run on each sentence of the reply, before it is spoken.
* **When several guardrails fire on the same text**, **Disconnect** wins over a message. When a caller-side guardrail answers with a message, the agent says it instead of asking the model.
* **Monitor** never changes the call. It only records.
* The checks on one piece of speech share a time budget of half a second. A check that runs out of time counts as no match.
* A function or macro can't set `user_number`, `call_id`, `current_date` or `current_time`.
* Rules that are switched off, and rules not added to the agent, don't run.

To see which guardrails were checked and which policies were used at each point of a call, open the call in [call details](https://docs.tryhamsa.com/agents/monitor/call-details.md) and use [**Debug mode**](https://docs.tryhamsa.com/agents/monitor/debug-mode.md).

## Good to know

* Start a guardrail in **Monitor**, watch a few calls, then switch it to **Enforce**.
* "Saved rules with issues won't publish." Fix the issues the editor lists.
* A **Per user response** rule shows "Indexing" after you save it. If it shows "Indexing failed", click **Retry indexing**.
* To delete a rule, "Remove it in each agent's settings first, then delete it here."
* **Import** and **Export** move rules, functions and macros between projects as a .json file.
* These are runtime checks. The prompt advice on [writing a prompt](https://docs.tryhamsa.com/agents/build/write-a-prompt.md) still applies.

## Related

> [card] [Protect personal data](https://docs.tryhamsa.com/agents/safety/personal-data.md)
>
> Hide phone numbers and emails from the model.

> [card] [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md)
>
> Write the checks and actions guardrails run.

> [card] [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md)
>
> See which rules fired on a call.

> [card] [Variables](https://docs.tryhamsa.com/agents/variables/overview.md)
>
> The values conditions and functions read.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.