OpenAI Guardrails: Python (Preview)

Add configurable safety and compliance checks to LLM applications. OpenAI Guardrails wraps the OpenAI Python client to validate inputs and outputs, and integrates with the OpenAI Agents SDK.

Configure guardrails · Documentation · Examples

Requires Python 3.11+. Install openai-guardrails:

pip install openai-guardrails

If your configuration uses Contains PII, also install its spaCy model during build or deployment:

python -m spacy download en_core_web_sm

For uv with spaCy 3.8, install the model wheel directly:

uv pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl

Contains PII validates and loads this model during client initialization; a missing or unloadable model fails configuration before any request. See the Contains PII guide for configuration options.

Quickstart

1. Create and export a pipeline configuration with the Guardrails wizard. Save it as guardrails_config.json in your working directory.
2. Set the OPENAI_API_KEY environment variable to your OpenAI API key.
3. Use GuardrailsOpenAI in place of OpenAI:

from pathlib import Path
from guardrails import GuardrailsOpenAI, GuardrailTripwireTriggered
client = GuardrailsOpenAI(config=Path("guardrails_config.json"))
try:
    # Chat Completions API
    chat = client.chat.completions.create(
        model="gpt-5",
        messages=[{"role": "user", "content": "Hello world"}],
    )
    print(chat.choices[0].message.content)
# Responses API
    response = client.responses.create(
        model="gpt-5",
        input="What are the main features of your premium plan?",
    )
    print(response.output_text)
except GuardrailTripwireTriggered:
    print("Message blocked by guardrails.")

For async and Azure clients, see the quickstart guide. Read about tripwire handling and streaming behavior before integrating those flows.

Agents SDK

Use GuardrailAgent with the OpenAI Agents SDK. This example uses the same config file and API key as the quickstart:

import asyncio
from pathlib import Path
from agents import InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered, Runner
from agents.run import RunConfig
from guardrails import GuardrailAgent
agent = GuardrailAgent(
    config=Path("guardrails_config.json"),
    name="Customer support agent",
    instructions="You help customers with their questions.",
)
async def main():
    try:
        result = await Runner.run(
            agent, "Hello, can you help me?", run_config=RunConfig(tracing_disabled=True)
        )
        print(result.final_output)
    except (InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered):
        print("Message blocked by guardrails.")
if __name__ == "__main__":
    asyncio.run(main())

See the Agents SDK integration guide for configuration and tool guardrails.

Evaluations

Measure guardrail performance on labeled datasets using the same exported configuration. Install the evaluation dependencies first (currently required for basic evaluation as well as benchmarking):

pip install "openai-guardrails[benchmark]"
python -m guardrails.evals.guardrail_evals \
  --config-path guardrails_config.json \
  --dataset-path data.jsonl

Save one JSON object per line in data.jsonl, with labels for the guardrails in your configuration. For a configuration containing Moderation and NSFW Text:

{"id": "sample_1", "data": "Hello world", "expected_triggers": {"Moderation": false, "NSFW Text": false}}

For the programmatic API, model comparisons, benchmark dependencies, and dataset options, see the evaluation guide.

Examples and Local Development

Clone the repository and install it with the example dependencies:

git clone https://github.com/openai/openai-guardrails-python.git
cd openai-guardrails-python
pip install -e ".[examples]"

Set OPENAI_API_KEY as above. Install the spaCy model from the installation section for examples that use Contains PII, including agents_sdk.py.

python examples/basic/hello_world.py
python examples/basic/agents_sdk.py

Explore the examples:

• Basic chatbot — async client with guardrails
• Agents SDK — agent with input and output checks
• Local models — OpenAI-compatible model endpoints
• Structured outputs
• PII masking
• Tripwire suppression

Available Guardrails

| Guardrail | Checks for | | --- | --- | | Keyword Filter | Configured keywords and phrases | | Competitors | Mentions of configured competitors | | Moderation | Content flagged by OpenAI's moderation API | | URL Filter | URLs against domain allowlists or blocklists | | Secret Keys | Potential API keys, secrets, and credentials | | Contains PII | Personally identifiable information | | Hallucination Detection | Claims against reference material in vector stores | | Jailbreak | Jailbreak attempts | | Prompt Injection Detection | Misaligned tool calls and tool outputs | | NSFW Text | Workplace-inappropriate content | | Off Topic Prompts | Content outside a configured topic or scope | | Custom Prompt Check | Violations of custom instructions |

License

MIT.

Disclaimers

Guardrails may use Third-Party Services such as the Presidio open-source framework, which are subject to their own terms and conditions and are not developed or verified by OpenAI.

Developers are responsible for implementing appropriate safeguards to prevent storage or misuse of sensitive or prohibited content (including but not limited to personal data, child sexual abuse material, or other illegal content). OpenAI disclaims liability for any logging or retention of such content by developers. Developers must ensure their systems comply with all applicable data protection and content safety laws, and should avoid persisting any blocked content generated or intercepted by Guardrails. Guardrails calls paid OpenAI APIs, and developers are responsible for associated charges.