DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Classes / LLMGuardrail
Class guardrails

LLMGuardrail: Reference Guide

By DevShelfHub

LLM-based output validator — declares pass/fail criteria and runs an LLM to enforce them.

See the CrewAI API reference index, CrewAI introduction, and core concepts for surrounding context.

What is LLMGuardrail?

LLMGuardrail packages a natural-language contract — a description plus explicit criteria bullets — that a secondary evaluator model checks against the primary agent's output. CrewAI wires it into Task execution so failures increment the guardrail retry counter (guardrail_max_retries on the Task) and successful passes let the pipeline continue. This pattern shines when rules are fuzzy: tone alignment, multi-clause policy checks, or "does this JSON contain the right semantic keys even if formatting drifts" where deterministic code would be brittle.

The tradeoff is cost and latency: every validation issues its own completion, so stacking LLMGuardrail with already-expensive tasks multiplies tokens. A pragmatic split is callable guardrails for structural invariants (regex, JSON parse, numeric ranges) and LLMGuardrail for subjective judgment calls. Also align the evaluator LLM with the task: a tiny fast model often suffices when criteria are crisp, while nuanced legal or medical review may need the same tier as the writer.

Observability-wise, failed guardrails emit dedicated events you can subscribe to for alerting — treat repeated failures as a prompt or criteria bug, not something to paper over with infinite retries.

When to Use

Format compliance, content policies, structured output enforcement.

Use Cases

  • • JSON schema enforcement
  • • Tone/safety policies
  • • Format compliance

Key Features

  • ✓ Declarative description + criteria
  • ✓ Retry loop
  • ✓ LLM-evaluated

When NOT to Use

Trivial regex checks — use a plain callable guardrail.

Notes

Criteria wording is executable spec

Ambiguous bullets like "sounds professional" produce flaky judgments. Rewrite as observable checks the evaluator can score consistently across retries.

Evaluator model mismatch

If the evaluator is far weaker than the writer, it may reject good outputs or accept bad ones. Match capability to risk and log disagreements for prompt tuning.

Retry storms

Low guardrail_max_retries with strict criteria can loop until the task errors. Surface failures to operators instead of silently raising limits in production.

Combine with callable guardrails

Run cheap structural validation first in a normal guardrail function, then LLMGuardrail for semantic checks — saves tokens and narrows failure modes.

Import

python 
from crewai import LLMGuardrail

Key Parameters

Parameter Type Default Purpose
description str — High-level intent of the validation.
criteria list[str] — Specific checks to apply.

Code Examples

Strict JSON envelope

python 
from crewai import LLMGuardrail, Task

guard = LLMGuardrail(
    description='Validate extraction JSON',
    criteria=[
        'Valid JSON object',
        'Contains keys title, summary, confidence',
        'confidence is a float between 0 and 1',
    ],
)

extract = Task(description='Extract article metadata', expected_output='JSON', agent=analyst, guardrail=guard)

Tone policy for customer-facing drafts

python 
tone_guard = LLMGuardrail(
    description='Ensure supportive customer tone',
    criteria=['No blame language', 'Includes next step for the customer', 'Under 120 words'],
)

Pair with guardrail_max_retries

python 
from crewai import Task

Task(
    description='Draft apology email',
    expected_output='Plain text email',
    agent=writer,
    guardrail=tone_guard,
    guardrail_max_retries=2,
)

Common Mistakes

❌ Putting a regex check inside an LLMGuardrail

✅ Use a plain function guardrail for cheap checks.

LLMGuardrail FAQ

What is LLMGuardrail in CrewAI?

LLM-based output validator — declares pass/fail criteria and runs an LLM to enforce them. LLMGuardrail packages a natural-language contract — a description plus explicit criteria bullets — that a secondary evaluator model checks against the primary agent's output. CrewAI wires it into Task execution so failures increment the guardrail retry counter (guardrail_max_retries on the Task) and successful passes let the pipeline continue. This pattern shines when rules are fuzzy: tone alignment, multi-clause policy checks, or "does this JSON contain the right semantic ke…

Which package defines the CrewAI class LLMGuardrail?

DevShelfHub maps LLMGuardrail to Python module crewai (package path crewai in this reference). Pin your installed crewai version and match imports to the snippet on this page.

When should I use LLMGuardrail?

Format compliance, content policies, structured output enforcement.

When should I avoid using LLMGuardrail?

Trivial regex checks — use a plain callable guardrail.

How do I import LLMGuardrail in Python?

from crewai import LLMGuardrail

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search 58 classes, 30 methods, and 16 decorators, each with runnable examples, parameters, common mistakes, and cross-links.