Build

Guardrails

Protect agent inputs and outputs with built-in safety checks or application-specific Python guardrails.

Last updated August 20, 2026

On this page

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.

Execution Flow

Input↓Input Guardrails↓Middleware (before)↓Agent Execution↓Middleware (after)↓Output Guardrails↓Response

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`

Configuration example

Configure input and output rules in the agent YAML:

agents/agent.yaml

guardrails:
  input:
    - type: prompt_injection
      mode: block
    - type: pii
      mode: redact
  output:
    - type: moderation
      mode: block
    - type: system_prompt_leakage
      mode: block

See 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 type, mode, direction, status, custom name, and violation message.

Span name: guardrail:prompt_injection, guardrail:pii, and similar
Status: passed, blocked, warned, or redacted
Mode: block, warn, or redact
Direction: input or output

Guardrail guides

Built-in Guardrails

Configure every built-in input and output check

Custom Guardrails

Write application-specific checks in Python

Agent Configuration

Configure guardrails in agent YAML

Runs & Traces

Inspect guardrail evaluations and violations