Guardrails

Built-in safeguards for input validation, PII detection, and prompt injection defense.

v2.1.0

Guardrails check the supplied run input before the main model context is built. Built-in checks cover selected PII patterns, literal prompt-injection phrases, and OpenAI moderation classifications. They do not guarantee safe input or automatically inspect the full context, such as history, dependencies, retrieved documents, or attached media. The moderation guardrail also submits supplied images to OpenAI.

Choose checks for your application's policy and evaluate their false positives and false negatives.

Agno included Guardrails

Agno provides some built-in guardrails you can use out of the box with your Agents and Teams:

To use the Agno included guardrails, you just need to import them and pass them to the Agent or Team with the pre_hooks parameter.

Guardrails are implemented as pre-hooks, which execute after session loading and dependency resolution, before the main model context is built.

For example, to use the PII Detection Guardrail:

from agno.guardrails import PIIDetectionGuardrail
from agno.agent import Agent
from agno.models.openai import OpenAIResponses

agent = Agent(
    name="Privacy-Protected Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    pre_hooks=[PIIDetectionGuardrail()],
)

You can see complete examples using the Agno Guardrails in the Usage section.

Handling a failed check

A guardrail blocks a run by raising InputCheckError. run() and arun() catch it and return RunStatus.error; streaming runs emit RunError or TeamRunError. Ordinary hook exceptions are logged and execution continues. If a check depends on a provider, convert provider or parsing failures into InputCheckError when validation is required. See the moderation example.

Install agno and openai in a virtual environment and set OPENAI_API_KEY before running the examples.

Custom Guardrails

You can create custom guardrails by extending the BaseGuardrail class. See the BaseGuardrail Reference for more details.

This is useful if you need to perform any check or transformation not handled by the built-in guardrails, or just to implement your own validation logic.

You will need to implement the check and async_check methods to perform your validation and raise exceptions when detecting undesired content.

Agno automatically uses the sync or async version of the guardrail based on whether you are running the agent with .run() or .arun().

For example, let's create a simple custom guardrail that checks if the input contains any URLs:

import re

from agno.exceptions import CheckTrigger, InputCheckError
from agno.guardrails import BaseGuardrail
from agno.run.agent import RunInput


class URLGuardrail(BaseGuardrail):
    """Guardrail to identify and stop inputs containing URLs."""

    def check(self, run_input: RunInput) -> None:
        """Raise InputCheckError if the input contains any URLs."""
        if isinstance(run_input.input_content, str):
            # Basic URL pattern
            url_pattern = r'https?://[^\s]+|www\.[^\s]+|[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}[^\s]*'
            if re.search(url_pattern, run_input.input_content):
                raise InputCheckError(
                    "The input seems to contain URLs, which are not allowed.",
                    check_trigger=CheckTrigger.INPUT_NOT_ALLOWED,
                )

    async def async_check(self, run_input: RunInput) -> None:
        """Raise InputCheckError if the input contains any URLs."""
        if isinstance(run_input.input_content, str):
            # Basic URL pattern
            url_pattern = r'https?://[^\s]+|www\.[^\s]+|[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}[^\s]*'
            if re.search(url_pattern, run_input.input_content):
                raise InputCheckError(
                    "The input seems to contain URLs, which are not allowed.",
                    check_trigger=CheckTrigger.INPUT_NOT_ALLOWED,
                )

Now you can use your custom guardrail in your Agent:

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

# Agent using our URLGuardrail
agent = Agent(
    name="URL-Protected Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    # Provide the Guardrails to be used with the pre_hooks parameter
    pre_hooks=[URLGuardrail()],
)

from agno.run import RunStatus

response = agent.run("Can you check what's in https://fake.com?")
if response.status == RunStatus.error:
    print("Request rejected or run failed")
elif response.status == RunStatus.completed:
    print(response.content)

Learn More

PII Detection

Detect and redact personally identifiable information

Prompt Injection Defense

Match configured prompt-injection phrases

OpenAI Moderation

Detect content that violates OpenAI's content policy

Developer Resources