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

# Guardrails

> Guardrails provide your persona with strict behavioral guidelines that will be rigorously followed throughout every conversation.

Guardrails act as a safety layer that works alongside your system prompt to enforce specific rules, restrictions, and behavioral patterns that your persona must adhere to during conversations.

For example, if you're creating a customer service persona for a financial institution, you can apply guardrails that prevent the persona from discussing a competitor's products, sharing sensitive financial data, or providing investment advice outside of approved guidelines.

Each guardrail is its own resource. Create, attach, edit, and delete guardrails independently via the [Guardrails API](/api-reference/guardrails/create-guardrails).

<Warning>
  Guardrails are not guaranteed to prevent all misbehavior. They serve as guidance to help steer conversations but should be used as part of a broader safety strategy.
</Warning>

<Note>
  Legacy API: [Legacy guardrail sets](/api-reference/guardrails/legacy-guardrail-sets).
</Note>

## Design tips

When designing your guardrails, keep a few things in mind:

* Be specific about what topics, behaviors, or responses should be restricted or avoided.
* Consider edge cases where participants might try to circumvent the guardrails through creative prompting.
* Ensure your guardrails complement, rather than contradict, your persona's system prompt and intended functionality.
* Test your guardrails with various conversation scenarios to ensure they activate appropriately without being overly restrictive.

Think of guardrails as consistent "reminders" to your persona that help maintain appropriate behavior throughout conversations.

## Writing guardrail prompts

Guardrails do two things for policy, safety, and compliance conditions:

* **Steer the persona** — the persona does its best to adhere to each guardrail throughout the conversation.
* **Flag violations** — guardrails are continuously evaluated in the background, and when one is violated it triggers callback / app-message logic (see [Delivery methods](#delivery-methods)) so you can react.

They do not drive workflow progression — for goal-oriented steps, use [Objectives](/sections/conversational-video-interface/persona/objectives).

Good guardrail prompts are clear, specific, testable, and robust to user variation. Pattern: `[who] [is doing what] [under what condition]`.

```json theme={null}
{
  "guardrail_name": "no_sensitive_data",
  "guardrail_prompt": "User is sharing full credit card numbers, social security numbers, or passwords"
}
```

```json theme={null}
{
  "guardrail_name": "single_user_only",
  "guardrail_prompt": "More than one person is visible in camera view",
  "modality": "visual"
}
```

**Guardrail vs. objective:**

* Use an **objective** for information collection or workflow progression.
* Use a **guardrail** to steer the persona away from a behavior and flag it when it happens.

## Create a guardrail

Use the [Create Guardrails](/api-reference/guardrails/create-guardrails) endpoint to create a guardrail. The response includes a `uuid` — use this value in the `guardrail_ids` list when attaching guardrails to a persona.

```sh theme={null}
curl --request POST \
  --url https://tavusapi.com/v2/guardrails \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "guardrail_name": "no_competitors",
    "guardrail_prompt": "Only mention products within Our Company Inc. during conversations; never discuss competitors.",
    "modality": "verbal",
    "tags": ["compliance"]
  }'
```

### Parameters

#### `guardrail_name`

A descriptive name for the guardrail. Only alphanumeric characters and underscores are allowed. Maximum 100 characters.

Example: `"no_competitors"`

#### `guardrail_prompt`

A text prompt that explains the behavior the persona must observe. Keep this prompt short and direct for best enforcement. Maximum 1,000 characters.

Example: `"Only mention products within Our Company Inc. during conversations, and never discuss competitors' products."`

#### `modality`

Whether the guardrail is enforced verbally or visually. Each guardrail is either `verbal` or `visual`, not both.

* `verbal` (default) — enforced against the participant's spoken or typed responses.
* `visual` — enforced against visual cues observed by Raven (e.g. confirming the participant is alone on camera).

#### `callback_url` (optional)

A URL that receives a notification when the guardrail is triggered. Maximum 2,048 characters. The callback payload includes the `conversation_id`, the guardrail's name, and its `guardrail_uuid`:

```json theme={null}
{
  "conversation_id": "<conversation_id>",
  "properties": {
    "guardrail": "<guardrail_name>",
    "guardrail_uuid": "<guardrail_uuid>"
  }
}
```

#### `tags` (optional)

A list of tags used to group guardrails. Tags enable bulk attachment to personas via `guardrail_tags` — see [Attach by tag](#attach-by-tag) below. A single tag can group up to 50 guardrails (the max attachable to one persona).

#### `app_message` (optional)

Whether triggering this guardrail emits a real-time app-message event on the conversation. Default `true`. Set to `false` to suppress the in-conversation event for guardrails you only want to observe server-side via `callback_url`. See [Delivery methods](#delivery-methods).

## Delivery methods

When a guardrail triggers during a conversation, you can be notified in three ways. Each is independent — combine them as needed.

#### App message

A real-time event delivered to your client over the conversation's app-message channel the moment the guardrail fires. Use this to react in-app — e.g. show a banner, log the trigger, or branch UI state. The event's `properties` include the `guardrail` name, its `guardrail_uuid`, and the violation `reason`.

Controlled by `app_message` on the guardrail (default `true`). Set it to `false` to suppress the in-conversation event for guardrails you only want to observe server-side.

#### Webhook callback

A `POST` to your `callback_url` with the conversation id, the guardrail's name, and its `guardrail_uuid`:

```json theme={null}
{
  "conversation_id": "<conversation_id>",
  "properties": {
    "guardrail": "<guardrail_name>",
    "guardrail_uuid": "<guardrail_uuid>"
  }
}
```

Use this when you want server-side notification independent of the client — e.g. to write to an audit log, page on-call, or trigger downstream automation. Set `callback_url` per guardrail.

## Attach guardrails to a persona

A persona can reference guardrails in two ways:

1. **Explicit list** — pass an array of guardrail UUIDs as `guardrail_ids` on the persona.
2. **By tag** — pass an array of tag names as `guardrail_tags`. Any guardrail you own with a matching tag is attached dynamically.

A persona can have up to 50 guardrails. `guardrail_ids` and `guardrail_tags` are each capped at 50 entries.

### Attach during persona creation

```sh theme={null}
curl --request POST \
  --url https://tavusapi.com/v2/personas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "system_prompt": "You are a health intake assistant.",
    "guardrail_ids": ["g1234567890ab", "g0987654321cd"],
    "guardrail_tags": ["compliance"]
  }'
```

### Attach by editing an existing persona

```sh theme={null}
curl --request PATCH \
  --url https://tavusapi.com/v2/personas/{persona_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '[
    { "op": "add", "path": "/guardrail_ids/-", "value": "g1234567890ab" },
    { "op": "replace", "path": "/guardrail_tags", "value": ["compliance", "healthcare"] }
  ]'
```

### Attach by tag

Tagging is the recommended pattern when you have a large or growing set of guardrails. Tag each guardrail at creation time and reference the tag on the persona — any new guardrail you tag is picked up by the persona automatically on the next conversation.

```sh theme={null}
# 1. Create guardrails tagged "healthcare"
curl --request POST \
  --url https://tavusapi.com/v2/guardrails \
  --header 'x-api-key: <api-key>' \
  --data '{
    "guardrail_name": "no_medical_advice",
    "guardrail_prompt": "Never provide medical advice outside approved guidelines.",
    "tags": ["healthcare"]
  }'

# 2. Attach by tag to the persona
curl --request PATCH \
  --url https://tavusapi.com/v2/personas/{persona_id} \
  --header 'x-api-key: <api-key>' \
  --data '[
    { "op": "add", "path": "/guardrail_tags/-", "value": "healthcare" }
  ]'
```

## Edit or delete a guardrail

Use [Patch Guardrails](/api-reference/guardrails/patch-guardrails) to update fields on an existing guardrail, or [Delete Guardrails](/api-reference/guardrails/delete-guardrails) to remove one. When a guardrail is deleted, it's automatically detached from any personas that reference it.

```sh theme={null}
# Update the prompt on a single guardrail
curl --request PATCH \
  --url https://tavusapi.com/v2/guardrails/g1234567890ab \
  --header 'x-api-key: <api-key>' \
  --data '[
    { "op": "replace", "path": "/guardrail_prompt", "value": "Updated, stricter prompt." }
  ]'
```

## Limits

| Limit                        | Value            |
| ---------------------------- | ---------------- |
| Guardrails per tag           | 50               |
| Guardrails per persona       | 50               |
| `guardrail_ids` per persona  | 50               |
| `guardrail_tags` per persona | 50               |
| `guardrail_prompt` length    | 1,000 characters |
| `guardrail_name` length      | 100 characters   |
| `callback_url` length        | 2,048 characters |
| Tags per guardrail           | 32               |
| Tag name length              | 64 characters    |

## Best practices

<Note>
  For best results, create focused, single-purpose guardrails and group them with tags by context (e.g. `healthcare`, `compliance`, `sales`). A healthcare consultation persona might attach `["healthcare", "compliance"]`, while an educational tutor persona attaches `["child_safety"]`.
</Note>