Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fai%2Fguardrails%2Fgetting_started.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%2Fgetting_started.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) # Getting started This guide walks you through integrating Coralogix Guardrails with your LLM application to protect against prompt injection attacks, PII leakage, and other security threats. By following these steps, you can start securing your AI applications in a few minutes. Use the domain selector at the top of this page to set your Coralogix [region](https://docs-docusaurus.kinsta.page/user-guides/account-management/account-settings/coralogix-domain/.md). The example commands and code snippets on this page update automatically to use the matching endpoints. ## What you need[​](#what-you-need "Direct link to What you need") * Python 3.10 or higher. * 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. * A **Send-Your-Data API key**, used as `CX_TOKEN`. Navigate to **Settings**, then **API Keys**. * Access to the Coralogix Guardrails SDK. * The `AI-GUARDRAILS:MANAGE` [permission](https://docs-docusaurus.kinsta.page/user-guides/aaa/access-control/permissions/permissions-list/.md). ## 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") ``` # Coralogix credentials export CX_GUARDRAILS_TOKEN="your-coralogix-guardrails-api-key" export CX_TOKEN="your-coralogix-send-your-data-key" export CX_ENDPOINT="ingress.eu2.coralogix.com" export CX_GUARDRAILS_ENDPOINT="https://api.eu2.coralogix.com/api/v1/guardrails/guard" # Optional: Application metadata for observability export CX_APPLICATION_NAME="my-app" export CX_SUBSYSTEM_NAME="my-subsystem" ``` ## Step 1: Test your connection[​](#step-1-test-your-connection "Direct link to Step 1: Test your connection") Before enabling production policies, verify that the Guardrails SDK is reachable: ``` import asyncio from cx_guardrails import Guardrails, GuardrailsAPIConnectionError async def main(): guardrails = Guardrails() try: response = await guardrails.test_connection() print("✓ Guardrails API is reachable!") print(f"Response: {response}") except GuardrailsAPIConnectionError as e: print(f"✗ Connection test failed: {e}") asyncio.run(main()) ``` Expected output: ``` ✓ Guardrails API is reachable! Response: results=[GuardrailResult(type='test_policy', detected=False, ...)] ``` ## Step 2: Set up OpenTelemetry export[​](#step-2-set-up-opentelemetry-export "Direct link to Step 2: Set up OpenTelemetry export") To send guardrail spans to Coralogix AI Center, set up OpenTelemetry trace export in your application. The Guardrails SDK uses the standard OpenTelemetry SDK — no Coralogix-specific exporter required. 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 ``` ## Step 3: Guard a prompt with observability[​](#step-3-guard-a-prompt-with-observability "Direct link to Step 3: Guard a prompt with observability") For production use, wrap your guardrail calls in a `guarded_session()` context manager. This creates a parent span that groups all guardrail evaluations together for OpenTelemetry tracing, making it easy to correlate traces and view the complete request flow in Coralogix. ``` import asyncio from openai import AsyncOpenAI from cx_guardrails import Guardrails, PII, PromptInjection, GuardrailsTriggered guardrails = Guardrails() async def main(): openai_client = AsyncOpenAI() user_message = "What is AI observability? Explain in one sentence." async with guardrails.guarded_session(): try: await guardrails.guard_prompt( prompt=user_message, guardrails=[PII(), PromptInjection()], ) print("User input passed") except GuardrailsTriggered as e: return print(f"Blocked: {e}") response = await openai_client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": user_message}, ], ) print(f"\nAI RESPONSE:\n{response.choices[0].message.content}") asyncio.run(main()) ``` Expected output: ``` User input passed AI RESPONSE: AI observability refers to the tools and practices used to monitor, analyze, and understand the behavior and performance of AI models and systems in real-time. ``` ## Step 4: Full guarded conversation[​](#step-4-full-guarded-conversation "Direct link to Step 4: Full guarded conversation") Guard both user input and LLM response in a complete flow: ``` import asyncio from openai import AsyncOpenAI from cx_guardrails import Guardrails, PII, PromptInjection, GuardrailsTriggered guardrails = Guardrails() openai_client = AsyncOpenAI() async def main(): user_message = "What is AI observability? Explain in one sentence." async with guardrails.guarded_session(): try: await guardrails.guard_prompt( prompt=user_message, guardrails=[PII(), PromptInjection()], ) print("User input passed") except GuardrailsTriggered as e: return print(f"Blocked: {e}") response = await openai_client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": user_message}, ], ) llm_response = response.choices[0].message.content try: await guardrails.guard_response( response=llm_response, prompt=user_message, guardrails=[PII()], ) print("LLM response passed") except GuardrailsTriggered as e: return print(f"Response blocked: {e}") print(f"\nAI RESPONSE:\n{llm_response}") asyncio.run(main()) ``` Expected output: ``` User input passed LLM response passed AI RESPONSE: AI observability refers to the tools and practices used to monitor, analyze, and understand the behavior and performance of AI models and systems in real-time. ``` ## View your data in Coralogix[​](#view-your-data-in-coralogix "Direct link to View your data in Coralogix") 1. Log into your Coralogix account. 2. Go to **AI Center**, then **Application Catalog** to see your application. 3. Select your application to view its detailed information. 4. Navigate to the **Guardrails** section to see the trace data for your guardrail evaluations. ## Troubleshoot[​](#troubleshoot "Direct link to Troubleshoot") **AI Explorer shows "This application is not guarded" but guardrails are firing.** Cause: The `application` and `subsystem` values used to register guardrails do not match the values applied to ingested traces. When traces are sent through an OpenTelemetry Collector, the collector derives application and subsystem from resource attributes — if those values disagree with the guardrail registration, AI Explorer cannot match traces to the guardrails. Fix: 1. Note the `application` and `subsystem` values used when registering your guardrails. 2. In your OpenTelemetry Collector configuration, set `application_name_attributes` to look at `cx.application.name` first, then fall back to `service.namespace`. 3. Set `subsystem_name_attributes` to look at `cx.subsystem.name` first, then fall back to `service.name`. 4. Set the `cx.application.name` and `cx.subsystem.name` resource attributes on your application to match the guardrail registration. **Guard API calls return 403 or 404.** Cause: The API key used as `CX_GUARDRAILS_TOKEN` lacks the `AI-GUARDRAILS:MANAGE` permission. A standard Send-Your-Data key does not work for the Guard API. Fix: Use a Team API key created with the **AiObservability** role preset, which includes `AI-GUARDRAILS:MANAGE`. See [What you need](#what-you-need) for the full key requirements. **A blocked prompt sent twice produces only one guardrail violation in AI Explorer.** Cause: Guardrail violations are aggregated at the trace level. If the second call runs in a new trace and that trace itself does not invoke the input guardrail again, no violation is recorded for it. Fix: Wrap the input check, the LLM call, and the response check inside a single `guardrails.guarded_session()` block, as shown in [Step 3](#step-3-guard-a-prompt-with-observability). All evaluations within the session are grouped on the same trace. ## Next steps[​](#next-steps "Direct link to Next steps") Apply ready-to-use policies for prompt injection, PII, and toxicity with [Guardrails prebuilt policies](https://docs-docusaurus.kinsta.page/user-guides/ai/guardrails/prebuilt_policies/.md).