Guardrails
Protect agent inputs and outputs with built-in safety checks or application-specific Python guardrails.
Overview
Guardrails are safety checks that run before and after agent execution. They protect against prompt injection attacks, PII leakage, toxic content, off-topic requests, and application-specific risks. Each rule has a mode that determines what happens when a violation is detected. Guardrails are configured directly in your agent YAML.
Start with built-in guardrails for common safety risks. Use custom guardrails when a check needs your own validation or authorization logic.
When an input guardrail blocks, the agent and before middleware are skipped and the rejection message is returned. The after middleware still runs on that rejection by default, so it can post-process every response. Set run_after_on_block: false under guardrails to skip it on a block instead.
Modes
| Mode | Behavior | Run Status |
|---|---|---|
block | Stop processing and return a rejection message, configurable with rejection_message. The agent never executes for an input violation; an unsafe output is replaced. | completed by default. Set fail_run: true to mark it failed. |
warn | Record the violation as a trace span and continue processing. | completed |
redact | Replace detected content with placeholders such as [EMAIL_REDACTED]. Available for pii and pii_leakage. | completed |
Quick Start
Add a security baseline to any agent with a few lines:
guardrails:
input:
- type: prompt_injection
mode: block
- type: pii
mode: redact
output:
- type: moderation
mode: block
- type: system_prompt_leakage
mode: blockSee the built-in guardrails reference for every rule and configuration option.
Observability
Every guardrail evaluation is recorded as a trace span. Violations appear in the traces timeline with the rule name, status, direction, provider, and detection details.
- Span name:
guardrail:prompt_injection,guardrail:pii, and similar - Status:
passed,blocked,warned, orredacted - Direction:
inputoroutput