OpenAI Guardrails (Python) Documentation
by OpenAI
Drop-in input and output validation for OpenAI apps and agents — PII, jailbreak and hallucination checks with a tripwire that halts the run.
Overview
The documentation runs Intro, Examples, Quickstart, Streaming vs Blocking, Tripwires, Checks, Evaluation Tool, and an API Reference covering Types, Exceptions, Runtime, Registry and Spec. The core model is a three-stage pipeline defined in a JSON config: preflight runs before the model call (for example PII masking), input runs alongside the call (for example jailbreak detection), and output runs on generated content (for example hallucination checks); stages are optional and combinable. Nine built-in checks ship with it — Moderation, URL Filter, Contains PII, Hallucination Detection, Jailbreak, NSFW Text, Off Topic Prompts, Prompt Injection Detection and Custom Prompt Check. Three client families apply them: GuardrailsOpenAI and GuardrailsAsyncOpenAI as drop-in replacements supporting Chat Completions, the Responses API and structured outputs; Azure variants; and GuardrailAgent for the OpenAI Agents SDK, which applies prompt-injection detection at the tool level and PII and jailbreak checks at agent input and output boundaries. Violations raise GuardrailTripwireTriggered, and error handling is explicitly fail-safe by default, switchable to fail-secure with raise_guardrail_errors=True. A hosted Guardrails Wizard at guardrails.openai.com generates the config, and a bundled evaluation harness benchmarks checks and produces ROC curves so thresholds come from data. Five worked examples cover basic usage, Agents SDK integration, local models, structured outputs and PII masking.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~2-3 hours to read the docs and run the examples; under an hour to wire in the first guardrail
- Provider
- OpenAI
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Define a three-stage guardrail pipeline — preflight, input and output — in JSON config
- ✓Mask PII before it reaches the model and detect it again in generated output
- ✓Add jailbreak and prompt-injection detection at both agent and tool boundaries
- ✓Catch a tripwire exception and degrade gracefully instead of crashing the request
- ✓Choose between fail-safe and fail-secure behaviour when a guardrail itself errors
- ✓Apply guardrails to streaming responses and understand what blocking mode costs you
- ✓Benchmark checks with the evaluation tool and set thresholds from measured ROC curves
- ✓Wrap the OpenAI Agents SDK with GuardrailAgent instead of hand-rolling validation code
Highlights
- •Drop-in client replacement — GuardrailsOpenAI swaps for OpenAI with no other code change, so an existing app gains checks in an afternoon
- •Ships an evaluation harness with ROC curves, so thresholds come from your data rather than a guess, which most guardrail libraries omit
- •Explicit about the fail-safe versus fail-secure choice, a decision most guardrail wrappers make silently on your behalf
- •Integrates with the OpenAI Agents SDK via GuardrailAgent, applying prompt-injection detection at tool level and PII and jailbreak checks at agent boundaries
- •Young and small — 225 GitHub stars and a preview-stage API — so treat it as a well-designed starting point, not a battle-tested standard
- •Works with Azure OpenAI, local models and third-party OpenAI-compatible endpoints, not only OpenAI's own API
Who It’s For
Best For
- ✓Engineers shipping an OpenAI-backed app that needs PII and jailbreak controls before launch
- ✓Teams using the OpenAI Agents SDK who want guardrails without writing their own layer
- ✓Anyone tuning safety thresholds who needs a way to measure false positives
Prerequisites
- •Working Python and familiarity with the OpenAI Python client
- •Understanding of async Python if you use the async clients or streaming mode
- •Some idea of your own risk surface — the library enforces a policy, it does not choose one
FAQ
What is OpenAI Guardrails (Python) Documentation?
Official documentation for OpenAI's MIT-licensed Guardrails package, which adds configurable safety and compliance checks to LLM applications and Agents SDK agents. Written for engineers who need PII masking, jailbreak detection and prompt-injection defenses on an app that is about to ship. After working through it you can define a staged guardrail pipeline in JSON, handle tripwire exceptions, and tune thresholds against measured false positives.
Is OpenAI Guardrails (Python) Documentation free?
OpenAI Guardrails (Python) Documentation is free to access.
What level is OpenAI Guardrails (Python) Documentation for?
OpenAI Guardrails (Python) Documentation is aimed at a intermediate audience. Recommended background: Working Python and familiarity with the OpenAI Python client, Understanding of async Python if you use the async clients or streaming mode, Some idea of your own risk surface — the library enforces a policy, it does not choose one.
How long does OpenAI Guardrails (Python) Documentation take?
Expect roughly ~2-3 hours to read the docs and run the examples; under an hour to wire in the first guardrail. Most learners work through it at their own pace.
What will I learn from OpenAI Guardrails (Python) Documentation?
You'll learn: Define a three-stage guardrail pipeline — preflight, input and output — in JSON config; Mask PII before it reaches the model and detect it again in generated output; Add jailbreak and prompt-injection detection at both agent and tool boundaries; Catch a tripwire exception and degrade gracefully instead of crashing the request; Choose between fail-safe and fail-secure behaviour when a guardrail itself errors; Apply guardrails to streaming responses and understand what blocking mode costs you; Benchmark checks with the evaluation tool and set thresholds from measured ROC curves; Wrap the OpenAI Agents SDK with GuardrailAgent instead of hand-rolling validation code.
Topics
Sources
This page was written from 3 sources, 1 on domains other than openai.github.io.