OpenAI Moderation Guardrail

Detect content policy violations using OpenAI's moderation API.

The OpenAI Moderation Guardrail is a built-in guardrail that detects content that violates OpenAI's content policy in the input of your Agents.

It makes a separate moderation API request before main-model generation. A moderation classification is an input-policy signal; it does not predict that a generation request would fail.

Set OPENAI_API_KEY for this check even when the main model uses a different provider. Install agno and openai in your virtual environment.

Usage

To use the OpenAI Moderation Guardrail, you need to import it and pass it to the Agent with the pre_hooks parameter:

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

openai_moderation_guardrail = OpenAIModerationGuardrail()

agent = Agent(
    name="OpenAI Moderation Guardrail Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    pre_hooks=[openai_moderation_guardrail],
)

Require moderation to succeed

The built-in guardrail propagates provider failures as ordinary exceptions. Agno logs ordinary hook exceptions and continues the run. Use this subclass when an unavailable moderation service must also block execution:

from agno.exceptions import InputCheckError
from agno.guardrails import OpenAIModerationGuardrail


class RequiredModeration(OpenAIModerationGuardrail):
    """Require a successful moderation check before main-model execution."""

    def check(self, run_input):
        try:
            super().check(run_input)
        except InputCheckError:
            raise
        except Exception as exc:
            raise InputCheckError("Moderation unavailable; request not processed.") from exc

    async def async_check(self, run_input):
        try:
            await super().async_check(run_input)
        except InputCheckError:
            raise
        except Exception as exc:
            raise InputCheckError("Moderation unavailable; request not processed.") from exc

Pass RequiredModeration() in pre_hooks and check the returned run status as shown in the complete example.

Moderation model

By default, the OpenAI Moderation Guardrail will use OpenAI's omni-moderation-latest model.

You can adjust which model is used for moderation by providing the moderation_model parameter:

openai_moderation_guardrail = OpenAIModerationGuardrail(
    moderation_model="omni-moderation-latest",
)

Moderation categories

You can specify which categories the guardrail should check for.

By default, the guardrail will consider all the existing moderation categories. You can check the list of categories in OpenAI's docs.

raise_for_categories selects specific categories. In the current implementation, category names containing slashes or hyphens can fail to match the OpenAI SDK's serialized field names when content is flagged. The resulting exception is not a policy rejection and the unwrapped guardrail lets the run continue. Use the default all-category mode until that mapping is corrected. Simple names such as violence and hate match:

openai_moderation_guardrail = RequiredModeration(
    raise_for_categories=["violence", "hate"],
)

Developer Resources