Tutorial

Quick start guide to use Protegrity Semantic Guardrails

Available Models

As of v1.1.1, the Semantic Guardrails product can:

  • Semantically analyze user messages in your application domains for customer-support, financial and healthcare.
  • Scan user and ai messages for PII using Protegrity Data Discovery if installed in the same network environment.

Quick Start

The following is a simple Python request example:

import requests

data = {
    "messages": [
        {
            "from": "user",
            "to": "ai",
            "content": "Hello, what's your name?",
            "processors": ["customer-support"],
        },
        {
            "from": "ai",
            "to": "user",
            "content": "My name is AI!",
            "processors": ["pii"],
        },
    ]
}

response = requests.post(
    "http://localhost:8001/pty/semantic-guardrail/v1.1/conversations/messages/scan",
    json=data,
)

print(response.status_code)
print(response.json())

Implementation

The recommended integration pattern evaluates a conversation each time it is updated with new messages. This applies to messages from either users or AI systems. The solution analyzes the full conversation for enhanced effectiveness. Identical input requests are cached internally for optimized performance.

import requests


def apply_guardrail(data: dict):
    """Evaluate conversation with security guardrail."""

    response = requests.post(
        "http://localhost:8001/pty/semantic-guardrail/v1.1/conversations/messages/scan",
        json=data,
    )

    if response.json()["batch"]["outcome"] == "rejected":
        print(response.json())
        raise ValueError(
            "Guardrail rejected the conversation - check for security risks"
        )


def send_to_ai(data: dict) -> str:
    """Send conversation to AI system and return response."""
    # Implementation specific to your AI system
    ai_output = ...
    return ai_output


# Initialize conversation
conversation = {"messages": []}

# Gather user input
conversation["messages"].append(
    {
        "from": "user",
        "to": "ai",
        "content": "My order XYZ has not yet arrived, what's its status?",
        "processors": ["customer-support"],
    }
)

# Apply security evaluation
apply_guardrail(conversation)

# Generate AI response
conversation["messages"].append(
    {
        "from": "ai",
        "to": "user",
        "content": send_to_ai(conversation),
        "processors": ["pii"],
    }
)

# Re-evaluate with complete conversation
apply_guardrail(conversation)

Advanced Usage

For more granular control, a custom threshold check can be implemented on the client side, based on numerical ['batch']['score'] output values. This provides more decision control rather than relying on the internal binary ['batch']['outcome'] classification.

Note on PII Detection

As of v1.1.1, Semantic Guardrials uses Protegrity’s v2.x Data Discovery. Semantic Guardrails leverages Data Discovery PII Detection for its internal algorithm but is not a PII detection service. For example, some PIIs detected by Data Discovery may be ignored by it. If you require a PII detection service, use Data Discovery.


Last modified : March 11, 2026