How openai/openai-guardrails-python works
OpenAI Guardrails is a Python SDK that wraps OpenAI clients and Agents SDK agents to apply configurable safety and compliance checks to inputs and outputs. The main flow loads configured guardrails, runs checks at pipeline stages, and returns results or raises a tripwire; PII checks can also mask input. Separate capabilities include conversation-aware checks and dataset evaluation. Edges reflect the excerpts, SOURCE INDEX references, or README; unsampled wiring is omitted where it cannot be established.
Main entry points: registry.py Guardrail registry · client.py OpenAI clients · runtime.py Pipeline runtime · _base_client.py Client orchestration
Components 24
API integrations
- OpenAI clients
src/guardrails/client.py - Guardrail agent
src/guardrails/agents.py - Chat resource
src/guardrails/resources/chat/chat.py - Responses resource
src/guardrails/resources/responses/responses.py - Streaming support
src/guardrails/_streaming.py - Client orchestration
src/guardrails/_base_client.py
Guardrail execution
- Pipeline runtime
src/guardrails/runtime.py - Guardrail registry
src/guardrails/registry.py - Guardrail specs
src/guardrails/spec.py - Tripwire results
src/guardrails/exceptions.py
Safety checks
- LLM-based checks
src/guardrails/checks/text/llm_base.py - Hallucination check
src/guardrails/checks/text/hallucination_detection.py - Keyword check
src/guardrails/checks/text/keywords.py - PII check
src/guardrails/checks/text/pii.py - Injection checks
src/guardrails/checks/text/prompt_injection_detection.py - URL check
src/guardrails/checks/text/urls.py - Other built-in checks
src/guardrails/checks/text
Shared support
- Context validation
src/guardrails/utils/context.py - Conversation normalization
src/guardrails/utils/conversation.py - Safety identifiers
src/guardrails/utils/safety_identifier.py
Evaluations
- Dataset evaluations
src/guardrails/evals/guardrail_evals.py
Other components
- Application developer
- OpenAI API
- Agents SDK
Connections 28
- Application developer → OpenAI clients: configures and calls
- OpenAI clients → Client orchestration: uses shared client
src/guardrails/client.py - OpenAI clients → Pipeline runtime: runs guardrails
src/guardrails/client.py - OpenAI clients → Chat resource: exposes chat
src/guardrails/client.py - OpenAI clients → Responses resource: exposes responses
src/guardrails/client.py - OpenAI clients → Streaming support: uses streaming
src/guardrails/client.py - OpenAI API → OpenAI clients: serves API calls
- Application developer → Guardrail agent: configures agent
- Guardrail agent → Pipeline runtime: runs guardrails
src/guardrails/agents.py - Agents SDK → Guardrail agent: runs agent
- Pipeline runtime → Guardrail registry: looks up specs
src/guardrails/runtime.py - Guardrail registry → Guardrail specs: stores specifications
src/guardrails/registry.py - Guardrail registry → Keyword check: registers check
src/guardrails/checks/text/keywords.py - Guardrail registry → PII check: registers check
src/guardrails/checks/text/pii.py - Guardrail registry → Hallucination check: registers check
src/guardrails/checks/text/hallucination_detection.py - Guardrail registry → URL check: registers check
src/guardrails/checks/text/urls.py - Guardrail registry → Injection checks: registers check
src/guardrails/checks/text/prompt_injection_detection.py - Guardrail registry → Other built-in checks: registers checks
src/guardrails/checks/text/llm_base.py - Hallucination check → LLM-based checks: uses LLM base
src/guardrails/checks/text/hallucination_detection.py - Injection checks → LLM-based checks: uses LLM base
src/guardrails/checks/text/prompt_injection_detection.py - Pipeline runtime → Context validation: validates context
src/guardrails/utils/context.py - Client orchestration → PII check: masks detected PII
src/guardrails/_base_client.py - Client orchestration → Conversation normalization: normalizes history
src/guardrails/_base_client.py - Chat resource → Safety identifiers: uses identifier
src/guardrails/resources/chat/chat.py - Responses resource → Safety identifiers: uses identifier
src/guardrails/resources/responses/responses.py - Pipeline runtime → Tripwire results: raises failures
src/guardrails/runtime.py - Application developer → Dataset evaluations: evaluates dataset
- Dataset evaluations → OpenAI clients: uses configured pipeline