ModerationProcessor

The ModerationProcessor is a hybrid processor that can be used for both input and output processing to provide content moderation using an LLM to detect inappropriate content across multiple categories. This processor helps maintain content safety by evaluating messages against configurable moderation categories with flexible strategies for handling flagged content.

Usage example

import { ModerationProcessor } from '@mastra/core/processors'

const processor = new ModerationProcessor({
  model: 'openrouter/openai/gpt-oss-safeguard-20b',
  threshold: 0.7,
  strategy: 'block',
  categories: ['hate', 'harassment', 'violence'],
  lastMessageOnly: true,
})

Constructor parameters

options:

Options

Configuration options for content moderation

Options

model:

MastraModelConfig

Model configuration for the moderation agent

errorStrategy?:

'warn' | 'strict'

How to handle failures from the internal model call. 'warn' is fail-open: it logs the failure and allows the content through unchanged. 'strict' is fail-closed: it stops processing with a tripwire.

categories?:

string[]

Categories to check for moderation. If not specified, uses default OpenAI categories

threshold?:

number

Confidence threshold for flagging (0-1). Content is flagged if any category score exceeds this threshold

strategy?:

'block' | 'warn' | 'filter'

Strategy when content is flagged: 'block' rejects with error, 'warn' logs warning but allows through, 'filter' removes flagged messages

instructions?:

string

Custom moderation instructions for the agent. If not provided, uses default instructions based on categories

includeScores?:

boolean

Whether to include confidence scores in logs. Useful for tuning thresholds and debugging

lastMessageOnly?:

boolean

Whether to run moderation only on the most recent message in the batch instead of checking every message. Use this to avoid an extra LLM call for each earlier message in long conversations.

chunkWindow?:

number

Number of previous chunks to include for context when moderating stream chunks. If set to 1, includes the previous part, etc. Only applies when bufferSize is 0.

bufferSize?:

number

Opt-in buffering for streamed text. When greater than 0, streamed text is held back and moderated in one LLM call when it ends a sentence, reaches this many characters, or a non-text part arrives. This makes far fewer LLM calls and catches content split across chunks. Recommended for production streaming, for example bufferSize: 200. With 0, every text chunk gets its own LLM call.

providerOptions?:

ProviderOptions

Provider-specific options passed to the internal moderation agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })

Returns

id:

string

Processor identifier set to 'moderation'

name:

string

Processor display name, always 'Moderation'

processInput:

(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<MastraDBMessage[]>

Processes input messages to moderate content before sending to LLM

processOutputStream:

(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never; tracingContext?: TracingContext }) => Promise<ChunkType | null | undefined>

Processes streaming output parts to moderate content during streaming

Extended usage example

Input processing

src/mastra/agents/moderated-agent.ts

import { Agent } from '@mastra/core/agent'
import { ModerationProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'moderated-agent',
  name: 'moderated-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [
    new ModerationProcessor({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      categories: ['hate', 'harassment', 'violence'],
      threshold: 0.7,
      strategy: 'block',
      instructions: 'Detect and flag inappropriate content in user messages',
      includeScores: true,
    }),
  ],
})

Output processing with batching

For production streaming, set bufferSize (for example bufferSize: 200) so ModerationProcessor makes one moderation call per sentence instead of one per chunk. Buffering also catches content that is split across chunks. Text then reaches the client in sentence-sized pieces.

When using ModerationProcessor as an output processor, it's recommended to combine it with BatchPartsProcessor to optimize performance. The BatchPartsProcessor batches stream chunks together before passing them to the moderator, reducing the number of LLM calls required for moderation.

src/mastra/agents/output-moderated-agent.ts

import { Agent } from '@mastra/core/agent'
import { BatchPartsProcessor, ModerationProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'output-moderated-agent',
  name: 'output-moderated-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  outputProcessors: [
    // Batch stream parts first to reduce LLM calls
    new BatchPartsProcessor({
      batchSize: 10,
    }),
    // Then apply moderation on batched content
    new ModerationProcessor({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      strategy: 'filter',
      chunkWindow: 1,
    }),
  ],
})

Related

• Guardrails