Processors

A file-based agent discovers processors from its processors/ directory. Use this page for the file-based convention; use the processors guide for built-in processors, custom processors, streaming behavior, and advanced patterns.

Files under processors/input/ run before messages reach the model. Files under processors/output/ run after the model responds. Each file default-exports one Processor, and the filename becomes its discovery key.

Quickstart

Add an input processor by placing a processor file under processors/input/:

src/mastra/agents/weather/processors/input/pii.ts

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

export default new PIIDetector({
  strategy: 'block',
})

This processor runs before user messages reach the model.

Add an output processor

Output processors are good for filtering or transforming model responses before they're returned. This example redacts PII from the final response.

src/mastra/agents/weather/processors/output/redact.ts

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

export default new PIIDetector({
  strategy: 'redact',
})

Ordering

Discovered processors are added after any processors defined in config.ts. That means config processors run first.

Ordering

config.inputProcessors → processors/input/* → model
model → config.outputProcessors → processors/output/* → response

If config.inputProcessors or config.outputProcessors is a function, discovered processors of that type are ignored with a warning because function-valued processors can't be statically merged.

Precedence with config

Use config.ts for processors that need to be created dynamically or shared across agents. Use file-based processors for static, per-agent processors that should be reviewed alongside the agent.

Precedence is:

1. Function-valued config.inputProcessors or config.outputProcessors
2. Array-valued config.inputProcessors or config.outputProcessors
3. Discovered files under processors/input/ or processors/output/

Visit the Processor reference for the full interface.