Guardrails - Tavus

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.

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.

Legacy API: Legacy guardrail sets.

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) so you can react.

They do not drive workflow progression — for goal-oriented steps, use Objectives. Good guardrail prompts are clear, specific, testable, and robust to user variation. Pattern: [who] [is doing what] [under what condition].

{
  "guardrail_name": "no_sensitive_data",
  "guardrail_prompt": "User is sharing full credit card numbers, social security numbers, or passwords"
}

{
  "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 endpoint to create a guardrail. The response includes a uuid — use this value in the guardrail_ids list when attaching guardrails to a persona.

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 and the guardrail’s name:

{
  "conversation_id": "<conversation_id>",
  "properties": {
    "guardrail": "<guardrail_name>"
  }
}

`tags` (optional)

A list of tags used to group guardrails. Tags enable bulk attachment to personas via guardrail_tags — see Attach by tag below. A single tag can group up to 10 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

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. 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 and the guardrail’s name:

{
  "conversation_id": "<conversation_id>",
  "properties": {
    "guardrail": "<guardrail_name>"
  }
}

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:

Explicit list — pass an array of guardrail UUIDs as guardrail_ids on the persona.
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 10 guardrails. guardrail_ids and guardrail_tags are each capped at 10 entries.

Attach during persona creation

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

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.

# 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 to update fields on an existing guardrail, or Delete Guardrails to remove one. When a guardrail is deleted, it’s automatically detached from any personas that reference it.

# 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	10
Guardrails per persona	10
`guardrail_ids` per persona	10
`guardrail_tags` per persona	10
`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

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"].

Documentation Index

​Design tips

​Writing guardrail prompts

​Create a guardrail

​Parameters

​guardrail_name

​guardrail_prompt

​modality

​callback_url (optional)

​tags (optional)

​app_message (optional)

​Delivery methods

​App message

​Webhook callback

​Attach guardrails to a persona

​Attach during persona creation

​Attach by editing an existing persona

​Attach by tag

​Edit or delete a guardrail

​Limits

​Best practices

Design tips

Writing guardrail prompts

Create a guardrail

Parameters

`guardrail_name`

`guardrail_prompt`

`modality`

`callback_url` (optional)

`tags` (optional)

`app_message` (optional)

Delivery methods

App message

Webhook callback

Attach guardrails to a persona

Attach during persona creation

Attach by editing an existing persona

Attach by tag

Edit or delete a guardrail

Limits

Best practices