Guardrails AI

Overview

Guardrails AI is an open-source Python framework for checking what goes into and comes out of a large language model (LLM). You combine small, reusable checks called validators into a Guard. The Guard runs those checks on a user's input before it reaches the model, on the model's output before it reaches the user, or both. When a check fails, the Guard can raise an error, fix the value, filter it out, or ask the model to try again.

It also helps generate structured data. You describe the shape you want, for example with a Pydantic model, and the Guard asks the model for output in that shape and validates it.

An everyday analogy: airport security. Bags go through a scanner on the way in, and some items are checked again at the gate. Each check looks for one kind of problem. If something fails, staff may confiscate it, ask you to repack, or stop you boarding. Guardrails sets up those checkpoints around an LLM call, and you choose the checks and the response to each failure.

What it is

The framework is released under the Apache 2.0 licence. It is primarily a Python library, with JavaScript access also documented.

Where it came from

Guardrails was created by Shreya Rajpal and first published on PyPI in early 2023, when many developers were struggling to get reliable, well-formed output from LLMs. Early versions centred on RAIL, an XML-based specification for describing expected output and its validators. The project later moved to plain Python and Pydantic as the main way to define structure.

A company, Guardrails AI, formed around the project. Its most visible addition was Guardrails Hub, launched as a shared place to publish and install validators, so that teams do not have to write common checks from scratch. Later releases added the server mode, streaming validation and an OpenAI-compatible proxy endpoint. In February 2025 the company published Guardrails Index, a benchmark comparing the accuracy and latency of guardrail checks across common categories. The package had reached version 0.11 by August 2026.

How it works

1. Install validators

You install the framework, configure the Hub CLI, and install the validators you need as packages.

2. Build a Guard

You attach validators to a Guard and set an on-fail action for each.

from guardrails import Guard, OnFailAction
from guardrails_ai.regex_match import RegexMatch

guard = Guard().use(
    RegexMatch, regex=r"\(?\d{3}\)?-? *\d{3}-? *-?\d{4}",
    on_fail=OnFailAction.EXCEPTION,
)
guard.validate("123-456-7890")  # passes

3. Validate input, output or both

You can call guard.validate(text) on any string, which suits checking a user message before sending it to a model. Or you can call the Guard around an LLM call, so it sends the prompt, receives the output and validates it in one step. Validators can run on the whole text or on pieces such as sentences, and some support streaming.

4. Handle failures

Each validator returns pass or fail, with details. The on-fail action then decides what happens:

• Exception: stop and raise an error for your code to handle.
• Fix: replace the value with a corrected version the validator proposes, such as masked PII.
• Filter or refrain: drop the failing field, or return nothing.
• Re-ask: send the model a follow-up explaining what failed and ask for a corrected answer.
• No-op: record the failure but let the value through.

5. Generate structured data

With Guard.for_pydantic(...), the Guard describes a schema to the model. Where the model supports function calling, it uses that; otherwise it adds the schema to the prompt. The output is parsed, checked against the schema and any field validators, and returned as validated data. See structured outputs.

6. Serve

For teams that want guards outside the application code, guardrails start runs them as a service. Applications can call it through the client or point an OpenAI-compatible SDK at the server's endpoint.

Key concepts and terms

A worked example

This is an illustrative scenario.

An insurance company's claims assistant drafts replies to customers. The team must prevent three problems: leaking other customers' personal data, promising payment amounts and badly formed output that breaks the ticketing system.

1. They define a Pydantic model with fields reply_text, next_step and needs_human, and create a Guard with Guard.for_pydantic.
2. On reply_text they add a PII validator with the fix action, so detected phone numbers and email addresses are masked rather than blocking the reply.
3. They add a custom validator that fails if the text contains a currency amount followed by "will be paid", with the re-ask action.
4. On the input side, they add a guard that flags very long messages and known jailbreak phrases with the exception action.
5. In a test of 500 historical tickets, the PII fixer masks values in 37 replies, the payment check triggers 22 re-asks of which 19 succeed on the first retry, and 3 replies are routed to staff. Every reply now parses.
6. Average latency rises by about 0.4 seconds per reply because of the extra checks and re-asks, which they accept.

Strengths and limitations

Strengths:

• Simple model: validators combined into guards with explicit failure handling.
• Large catalogue of ready-made validators on the Hub.
• Works on inputs and outputs, with any model, including local ones.
• Structured output support with Pydantic.
• Apache 2.0 licence; can run in-process or as a server.

Limitations:

• Each validator adds latency, and model-based validators add cost.
• Re-asking may fail repeatedly and increases token use.
• Validators can miss attacks or flag harmless text; no check is perfect.
• It validates content, not dialogue flow; conversation steering needs other tools.
• Quality varies across community validators, so each needs testing.

How it compares with alternatives

Practical guidance and best practices

1. List the specific risks first, then pick one validator per risk.
2. Prefer fast rule-based validators; add model-based ones only where needed.
3. Use the fix action for things that can be corrected safely, such as masking PII.
4. Limit re-asks to one or two, and send failures to a human or a safe fallback.
5. Test each validator on real examples for both missed problems and false alarms.
6. Log validation outcomes and review them regularly.
7. Combine input and output guards; one side alone leaves gaps.
8. Treat guardrails as one layer alongside prompt injection defence, access control and monitoring.

Common mistakes

• Adding many validators without measuring the latency they add.
• Using re-ask everywhere, multiplying cost and delay.
• Trusting community validators without testing them on your data.
• Relying on output checks alone to stop prompt injection.
• Ignoring validators set to no-op, so failures are logged but never reviewed.

Frequently asked questions

What is a validator?

A validator is a single check on a piece of text or a field, such as "matches this pattern", "contains no toxic language" or "mentions no competitor". It returns pass or fail and can suggest a fixed value. Validators are combined into Guards.

Does Guardrails work with any model?

Yes. It can wrap calls to hosted and open-source models, and guard.validate works on any text, wherever it came from.

What does re-asking do?

When an output fails, the Guard sends the model a new request explaining what was wrong and asks for a corrected answer. It often works but costs extra calls and time.

Is Guardrails the same as NeMo Guardrails?

No. They are separate projects. Guardrails AI focuses on validating inputs and outputs with reusable validators. NeMo Guardrails, from NVIDIA, focuses on programmable rails and dialogue flows defined in Colang. They can be used together.

Can I write my own validators?

Yes. You can write custom validators in Python and, if you wish, publish them to the Hub.

Can it run as a separate service?

Yes. guardrails start runs guards as a REST service, including an OpenAI-compatible endpoint, so several applications can share the same checks.

Glossary

• LLM: a large language model that generates text.
• PII: personally identifiable information such as names, emails and phone numbers.
• Pydantic: a Python library for defining and validating data models.
• Function calling: a model feature that returns structured arguments for a tool, see function calling.
• False positive: harmless text wrongly flagged.
• False negative: a real problem that a check misses.
• Proxy endpoint: a server that sits between an application and a model API.

Summary

Guardrails AI is an open-source Python framework that wraps LLM calls with validators for format, safety and data quality. Guards run on inputs, outputs or both, and each failure is handled explicitly by raising, fixing, filtering or re-asking. It also generates validated structured output from Pydantic models and can run as a service. Choose validators for specific risks, test them on real data, watch latency and cost, and combine them with other defences. See guardrails for the wider concept.

Related

It belongs to LLM safety in my stack, under Generative AI and LLMs. Others in the same group: