Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fai%2Fguardrails%2Fcustom_policies.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fai%2Fguardrails%2Fcustom_policies.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) # Custom guardrail policies Custom guardrails allow you to define domain-specific protection policies using natural language instructions, based on your unique business rules, compliance requirements, or application-specific constraints. ## What you need[​](#what-you-need "Direct link to What you need") * Python 3.10 or higher. * `cx-guardrails` installed. See [Getting Started with Guardrails](https://docs-docusaurus.kinsta.page/user-guides/ai/guardrails/getting_started/.md). * The `AI-GUARDRAILS:MANAGE` [permission](https://docs-docusaurus.kinsta.page/user-guides/aaa/access-control/permissions/permissions-list/.md). * A [Team API key](https://docs-docusaurus.kinsta.page/user-guides/account-management/api-keys/api-keys/.md) with the **AiObservability** role preset, used as `CX_GUARDRAILS_TOKEN`. The AiObservability preset includes `AI-GUARDRAILS:MANAGE` and all other permissions required to use Guardrails. ## Install the SDK[​](#install-the-sdk "Direct link to Install the SDK") ``` pip install cx-guardrails ``` ## Set up environment variables[​](#set-up-environment-variables "Direct link to Set up environment variables") ``` export CX_GUARDRAILS_TOKEN="your-coralogix-guardrails-api-key" export CX_GUARDRAILS_ENDPOINT="https://api..coralogix.com/api/v1/guardrails/guard" export CX_TOKEN="your-coralogix-send-your-data-key" export CX_ENDPOINT="https://your-domain.coralogix.com" # Optional: Application metadata for observability export CX_APPLICATION_NAME="my-app" export CX_SUBSYSTEM_NAME="my-subsystem" ``` ## Set up observability[​](#set-up-observability "Direct link to Set up observability") To send guardrail spans to AI Center, set up OpenTelemetry trace export. For the full overview, see [OpenTelemetry integration for AI Center](https://docs-docusaurus.kinsta.page/user-guides/ai/otel-integration/.md). Install the OpenTelemetry packages: ``` pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc ``` Export the OTLP environment variables: ``` export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingress.eu2.coralogix.com:443" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer " export OTEL_SERVICE_NAME="my-ai-service" export OTEL_RESOURCE_ATTRIBUTES="cx.application.name=my-app,cx.subsystem.name=my-subsystem" export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental ``` Initialize the tracer provider in your application before any guardrail or LLM calls: ``` from opentelemetry import trace from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor def configure_otel() -> TracerProvider: resource = Resource.create() provider = TracerProvider(resource=resource) provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) trace.set_tracer_provider(provider) return provider ``` ## Understanding custom guardrails[​](#understanding-custom-guardrails "Direct link to Understanding custom guardrails") Custom guardrails are configured using the `Custom` class, which requires: * **name**: A unique identifier for your guardrail. * **instructions**: Natural language description of what to evaluate. Must include at least one of `{prompt}`, `{response}`, or `{history}`. * **Prohibited**: Description of what constitutes a violation. * **Acceptable**: Description of what is considered safe. * **examples** (optional): Training examples to improve detection accuracy. * **threshold**: Detection sensitivity (0.0 to 1.0, default 0.7). * **`should_include_system_prompt`** (optional): Whether to include the system prompt when guardrails run their check. ## Instructions[​](#instructions "Direct link to Instructions") Natural language description of what to evaluate. Must include `{prompt}`, `{response}`, or `{history}`. ### Magic variables[​](#magic-variables "Direct link to Magic variables") Custom guardrails support special variables in the `instructions` field: | Variable | Description | Usage | | ------------ | ------------------------- | ----------------------------- | | `{prompt}` | The user's input prompt | Evaluate prompt content | | `{response}` | The LLM's response | Evaluate response content | | `{history}` | Full conversation history | Evaluate context across turns | Your `instructions` must include at least one of these variables. ## Configuration options[​](#configuration-options "Direct link to Configuration options") ### Reference examples[​](#reference-examples "Direct link to Reference examples") **Reference examples are crucial for improving guardrail accuracy.** While optional, providing examples significantly enhances detection quality by giving the LLM evaluator concrete references of what constitutes a violation versus safe behavior in your specific context. Each example is a conversation between the user and the LLM, scored as either: * **score=1**: Violates the policy (should be blocked). * **score=0**: Safe behavior (should be allowed). Aim for at least 3–5 examples covering different scenarios, edge cases, and borderline situations. Examples can include multi-turn conversations to capture violations that emerge over multiple interactions. ### Including the system prompt[​](#including-the-system-prompt "Direct link to Including the system prompt") Use `should_include_system_prompt` to decide whether to include the system prompt when guardrails run their check. ## Best practices[​](#best-practices "Direct link to Best practices") ### Writing effective instructions[​](#writing-effective-instructions "Direct link to Writing effective instructions") 1. **Be specific**: Clearly describe what you're looking for. 2. **Use examples**: Provide training examples for better accuracy. 3. **Include context**: Use `{history}` for context-aware detection. 4. **Test iteratively**: Adjust instructions based on results. ``` # Too vague instructions="Check if the {response} is bad" # Specific and clear instructions="""Evaluate if the {response} contains speculation about future events without proper uncertainty language (e.g., 'might', 'could', 'possibly').""" ``` ## Example: Financial advice detection[​](#example-financial-advice-detection "Direct link to Example: Financial advice detection") Detect when LLM responses provide specific financial advice without proper disclaimers: ``` FINANCIAL_ADVICE_DETECTOR = Custom( name="financial_advice_detector", instructions=( "Analyze the {response} for specific financial advice that could be construed as " "professional investment recommendations. Focus on whether the response recommends " "specific stocks, cryptocurrencies, funds, or investment allocations without appropriate disclaimers." ), violates=( "The response provides specific investment recommendations — such as 'buy this stock' or " "'put your money in Y fund', or suggests specific portfolio allocations (e.g. '60% stocks') — " "without including a clear disclaimer that the information is not professional financial advice." ), safe=( "The response does one or more of the following: " "(1) does not discuss specific investments at all, " "(2) provides only general educational information about financial concepts, " "(3) discusses investments but includes a clear disclaimer that it is not professional financial " "advice and recommends consulting a licensed advisor, or (4) declines to give investment advice entirely." ), examples=[ CustomEvaluationExample( conversation=( "User: Should I buy Tesla stock?\n" "Assistant: Yes, Tesla is a strong buy right now. The stock is undervalued and I expect it " "to double within the next year. You should invest at least 20% of your portfolio in it." ), score=1, ), CustomEvaluationExample( conversation=( "User: I just inherited $100,000. What should I do with it?\n" "Assistant: That's a significant amount! Are you looking to invest it or save it for something specific?\n" "User: I want to grow it. I'm 30 and don't need it right now.\n" "Assistant: Great, with a long time horizon you can be more aggressive. Here's what I'd do: " "put $60,000 into a tech-heavy ETF like QQQ, $25,000 into Bitcoin since it's still early, " "and keep $15,000 as cash reserves. Start the ETF position this week while prices are low." ), score=1, ), CustomEvaluationExample( conversation=( "User: Is gold a good investment?\n" "Assistant: Absolutely, you should buy gold ETFs like GLD now before prices go up further." ), score=1, ), CustomEvaluationExample( conversation=( "User: What is a stock?\n" "Assistant: A stock represents a share of ownership in a company. When you purchase stock, " "you become a partial owner (shareholder) of that company. Stocks are traded on exchanges like the NYSE and NASDAQ." ), score=0, ), CustomEvaluationExample( conversation=( "User: What's an ETF?\n" "Assistant: An ETF (Exchange-Traded Fund) is a basket of securities that trades on an exchange like a stock." ), score=0, ), CustomEvaluationExample( conversation=( "User: Should I invest in index funds or individual stocks?\n" "Assistant: Index funds offer diversification and lower risk, while individual stocks have higher " "potential returns but more volatility. This is educational information only, not financial advice. " "Please consult a licensed financial advisor for personalized recommendations." ), score=0, ), ], category=GuardrailCategory.QUALITY, ) ``` ## Next steps[​](#next-steps "Direct link to Next steps") Use the `guard()` method for full control over multi-turn conversation guardrail evaluation with [Guard API](https://docs-docusaurus.kinsta.page/user-guides/ai/guardrails/guard_api/.md).