Introduction
OpenGuardrails (OGR) is an open guardrails contract for AI agents. The whole
protocol fits in one sentence: an interception point observes an agent action,
packages it as a GuardEvent, submits it to a
runtime, and gets back a Verdict — allow,
block, require_approval, modify, or redact — which it enforces before the
action proceeds.
Because the contract is neutral, any agent framework, any gateway, any sandbox, and any safety/security detector interoperate without custom glue. You wire an agent once, then swap detectors and enforcement backends as configuration.
The layering: API → SDK → Plugin
Everything in these docs sits on one of three layers:
| Layer | What it is | Where documented |
|---|---|---|
| API | The wire contract: the /v1/* HTTP endpoints plus the GuardEvent and Verdict JSON Schemas. Anything that speaks it conforms. | API reference |
| SDK | A language binding wrapping the API — serialization, auth, request signing, batching. openguardrails on PyPI, @openguardrails/core on npm. | SDKs |
| Plugin | A hook for one surface (agent, gateway, sandbox, eBPF) built on an SDK — install it and a real agent is guarded with no code. | Plugins |
Work at the lowest layer you need: install a plugin if one exists for your stack, use an SDK to instrument your own agent, and drop to the raw API only when you are implementing a runtime or a binding for a new language.
What the contract standardizes
- GuardEvent — one observed action at one
of three altitudes (
conversation,invocation,execution), with provenance describing where its inputs came from. - Verdict — a detector's decision, with risk
categories from a shared taxonomy (
safety.*,security.*,privacy.*). - Composition — how a runtime merges many detectors' verdicts into the one decision that is enforced.
- The Runtime API — the HTTP binding every SDK ships with: evaluate, ingest, enrollment, heartbeat, degraded-mode config, approvals.
Where to go next
- Quickstart — first verdict in minutes: curl, then the Python and JS SDKs, then a plugin.
- API reference — every endpoint, header, error, and field.
- Instrument your agent — connect a framework OGR doesn't know about yet.
OGR is Apache-2.0 and governance-neutral. Detectors compete on a neutral benchmark; you compose the winners.