@mastra/core 1.15.0-alpha.0 → 1.15.0-alpha.2

package/dist/docs/references/docs-agents-guardrails.md

@@ -1,50 +1,16 @@
 # Guardrails
 
-Agents use processors to apply guardrails to inputs and outputs. They run before or after each interaction, giving you a way to review, transform, or block information as it passes between the user and the agent.
+Mastra provides built-in processors that add security and safety controls to your agent. These processors detect, transform, or block harmful content before it reaches the language model or the user.
 
-Processors can be configured as:
-
-- **`inputProcessors`**: Applied before messages reach the language model.
-- **`outputProcessors`**: Applied to responses before they're returned to users.
-
-Some processors are _hybrid_, meaning they can be used with either `inputProcessors` or `outputProcessors`, depending on where the logic should be applied.
-
-## When to use processors
-
-Use processors for content moderation, prompt injection prevention, response sanitization, message transformation, and other security-related controls. Mastra provides several built-in input and output processors for common use cases.
-
-## Adding processors to an agent
-
-Import and instantiate the relevant processor class, and pass it to your agent’s configuration using either the `inputProcessors` or `outputProcessors` option:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { ModerationProcessor } from '@mastra/core/processors'
-
-export const moderatedAgent = new Agent({
-  id: 'moderated-agent',
-  name: 'Moderated Agent',
-  instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
-  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',
-    }),
-  ],
-})
-```
+For an introduction to how processors work, how to add them to an agent, and how to create custom processors, see [Processors](https://mastra.ai/docs/agents/processors).
 
 ## Input processors
 
-Input processors are applied before user messages reach the language model. They're useful for normalization, validation, content moderation, prompt injection detection, and security checks.
+Input processors run before user messages reach the language model. They handle normalization, validation, prompt injection detection, and security checks.
 
-### Normalizing user messages
+### Normalize user messages
 
-The `UnicodeNormalizer` is an input processor that cleans and normalizes user input by unifying Unicode characters, standardizing whitespace, and removing problematic symbols, allowing the LLM to better understand user messages.
+The `UnicodeNormalizer()` cleans and normalizes user input by unifying Unicode characters, standardizing whitespace, and removing problematic symbols.
 
 ```typescript
 import { UnicodeNormalizer } from '@mastra/core/processors'
@@ -61,11 +27,11 @@ export const normalizedAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [UnicodeNormalizer](https://mastra.ai/reference/processors/unicode-normalizer) for a full list of configuration options.
+> **Note:** Visit [`UnicodeNormalizer()`](https://mastra.ai/reference/processors/unicode-normalizer) reference for a full list of configuration options.
 
-### Preventing prompt injection
+### Prevent prompt injection
 
-The `PromptInjectionDetector` is an input processor that scans user messages for prompt injection, jailbreak attempts, and system override patterns. It uses an LLM to classify risky input and can block or rewrite it before it reaches the model.
+The `PromptInjectionDetector()` scans user messages for prompt injection, jailbreak attempts, and system override patterns. It uses an LLM to classify risky input and can block or rewrite it before it reaches the model.
 
 ```typescript
 import { PromptInjectionDetector } from '@mastra/core/processors'
@@ -84,11 +50,11 @@ export const secureAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector) for a full list of configuration options.
+> **Note:** Visit [`PromptInjectionDetector()`](https://mastra.ai/reference/processors/prompt-injection-detector) reference for a full list of configuration options.
 
-### Detecting and translating language
+### Detect and translate language
 
-The `LanguageDetector` is an input processor that detects and translates user messages into a target language, enabling multilingual support while maintaining consistent interaction. It uses an LLM to identify the language and perform the translation.
+The `LanguageDetector()` detects and translates user messages into a target language, enabling multilingual support. It uses an LLM to identify the language and perform the translation.
 
 ```typescript
 import { LanguageDetector } from '@mastra/core/processors'
@@ -107,15 +73,15 @@ export const multilingualAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [LanguageDetector](https://mastra.ai/reference/processors/language-detector) for a full list of configuration options.
+> **Note:** Visit [`LanguageDetector()`](https://mastra.ai/reference/processors/language-detector) reference for a full list of configuration options.
 
 ## Output processors
 
-Output processors are applied after the language model generates a response, but before it's returned to the user. They're useful for response optimization, moderation, transformation, and applying safety controls.
+Output processors run after the language model generates a response, but before it reaches the user. They handle response optimization, moderation, transformation, and safety controls.
 
-### Batching streamed output
+### Batch streamed output
 
-The `BatchPartsProcessor` is an output processor that combines multiple stream parts before emitting them to the client. This reduces network overhead and improves the user experience by consolidating small chunks into larger batches.
+The `BatchPartsProcessor()` combines multiple stream parts before emitting them to the client. This reduces network overhead by consolidating small chunks into larger batches.
 
 ```typescript
 import { BatchPartsProcessor } from '@mastra/core/processors'
@@ -133,33 +99,11 @@ export const batchedAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [BatchPartsProcessor](https://mastra.ai/reference/processors/batch-parts-processor) for a full list of configuration options.
-
-### Limiting token usage
-
-The `TokenLimiterProcessor` is an output processor that limits the number of tokens in model responses. It helps manage cost and performance by truncating or blocking messages when the limit is exceeded.
-
-```typescript
-import { TokenLimiterProcessor } from '@mastra/core/processors'
-
-export const limitedAgent = new Agent({
-  id: 'limited-agent',
-  name: 'Limited Agent',
-  outputProcessors: [
-    new TokenLimiterProcessor({
-      limit: 1000,
-      strategy: 'truncate',
-      countMode: 'cumulative',
-    }),
-  ],
-})
-```
-
-> **Info:** Visit [TokenLimiterProcessor](https://mastra.ai/reference/processors/token-limiter-processor) for a full list of configuration options.
+> **Note:** Visit [`BatchPartsProcessor()`](https://mastra.ai/reference/processors/batch-parts-processor) reference for a full list of configuration options.
 
-### Scrubbing system prompts
+### Scrub system prompts
 
-The `SystemPromptScrubber` is an output processor that detects and redacts system prompts or other internal instructions from model responses. It helps prevent unintended disclosure of prompt content or configuration details that could introduce security risks. It uses an LLM to identify and redact sensitive content based on configured detection types.
+The `SystemPromptScrubber()` detects and redacts system prompts or internal instructions from model responses. It prevents unintended disclosure of prompt content or configuration details. It uses an LLM to identify and redact sensitive content based on configured detection types.
 
 ```typescript
 import { SystemPromptScrubber } from '@mastra/core/processors'
@@ -182,17 +126,17 @@ const scrubbedAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [SystemPromptScrubber](https://mastra.ai/reference/processors/system-prompt-scrubber) for a full list of configuration options.
+> **Note:** Visit [`SystemPromptScrubber()`](https://mastra.ai/reference/processors/system-prompt-scrubber) reference for a full list of configuration options.
 
 > **Note:** When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](https://mastra.ai/docs/server/mastra-server) for details.
 
 ## Hybrid processors
 
-Hybrid processors can be applied either before messages are sent to the language model or before responses are returned to the user. They're useful for tasks like content moderation and PII redaction.
+Hybrid processors can run on either input or output. Place them in `inputProcessors`, `outputProcessors`, or both.
 
-### Moderating input and output
+### Moderate input and output
 
-The `ModerationProcessor` is a hybrid processor that detects inappropriate or harmful content across categories like hate, harassment, and violence. It can be used to moderate either user input or model output, depending on where it's applied. It uses an LLM to classify the message and can block or rewrite it based on your configuration.
+The `ModerationProcessor()` detects inappropriate or harmful content across categories like hate, harassment, and violence. It uses an LLM to classify the message and can block or rewrite it based on your configuration.
 
 ```typescript
 import { ModerationProcessor } from '@mastra/core/processors'
@@ -212,11 +156,11 @@ export const moderatedAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [ModerationProcessor](https://mastra.ai/reference/processors/moderation-processor) for a full list of configuration options.
+> **Note:** Visit [`ModerationProcessor()`](https://mastra.ai/reference/processors/moderation-processor) reference for a full list of configuration options.
 
-### Detecting and redacting PII
+### Detect and redact PII
 
-The `PIIDetector` is a hybrid processor that detects and removes personally identifiable information such as emails, phone numbers, and credit cards. It can redact either user input or model output, depending on where it's applied. It uses an LLM to identify sensitive content based on configured detection types.
+The `PIIDetector()` detects and removes personally identifiable information such as emails, phone numbers, and credit cards. It uses an LLM to identify sensitive content based on configured detection types.
 
 ```typescript
 import { PIIDetector } from '@mastra/core/processors'
@@ -238,67 +182,32 @@ export const privateAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [PIIDetector](https://mastra.ai/reference/processors/pii-detector) for a full list of configuration options.
-
-## Applying multiple processors
-
-You can apply multiple processors by listing them in the `inputProcessors` or `outputProcessors` array. They run in sequence, with each processor receiving the output of the one before it.
-
-A typical order might be:
-
-1. **Normalization**: Standardize input format (`UnicodeNormalizer`).
-2. **Security checks**: Detect threats or sensitive content (`PromptInjectionDetector`, `PIIDetector`).
-3. **Filtering**: Block or transform messages (`ModerationProcessor`).
-
-The order affects behavior, so arrange processors to suit your goals.
-
-```typescript
-import {
-  UnicodeNormalizer,
-  ModerationProcessor,
-  PromptInjectionDetector,
-  PIIDetector,
-} from '@mastra/core/processors'
-
-export const testAgent = new Agent({
-  id: 'test-agent',
-  name: 'Test Agent',
-  inputProcessors: [
-    new UnicodeNormalizer(),
-    new PromptInjectionDetector(),
-    new PIIDetector(),
-    new ModerationProcessor(),
-  ],
-})
-```
+> **Note:** Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) reference for a full list of configuration options.
 
 ## Processor strategies
 
-Many of the built-in processors support a `strategy` parameter that controls how they handle flagged input or output. Supported values may include: `block`, `warn`, `detect`, or `redact`.
+Many built-in processors support a `strategy` parameter that controls how they handle flagged content. Supported values include: `block`, `warn`, `detect`, `redact`, `rewrite`, and `translate`.
 
-Most strategies allow the request to continue without interruption. When `block` is used, the processor calls its internal `abort()` function, which immediately stops the request and prevents any subsequent processors from running.
+Most strategies allow the request to continue. When `block` is used, the processor calls `abort()`, which stops the request immediately and prevents subsequent processors from running.
 
 ```typescript
-import { PIIDetector } from '@mastra/core/processors'
-
-export const privateAgent = new Agent({
-  id: 'private-agent',
-  name: 'Private Agent',
-  inputProcessors: [
-    new PIIDetector({
-      strategy: 'block',
-    }),
-  ],
-})
+inputProcessors: [
+  new PIIDetector({
+    model: 'openrouter/openai/gpt-oss-safeguard-20b',
+    threshold: 0.6,
+    strategy: 'block',
+    detectionTypes: ['email', 'phone', 'credit-card'],
+  }),
+]
 ```
 
-### Handling blocked requests
+## Handle blocked requests
 
-When a processor blocks a request, the agent will still return successfully without throwing an error. To handle blocked requests, check for `tripwire` in the response.
+When a processor calls `abort()`, the agent stops processing. How you detect this depends on whether you use `generate()` or `stream()`.
 
-For example, if an agent uses the `PIIDetector` with `strategy: "block"` and the request includes a credit card number, it will be blocked and the response will include tripwire information.
+### With `generate()`
 
-#### `.generate()` example
+Check the `tripwire` field on the result:
 
 ```typescript
 const result = await agent.generate('Is this credit card number valid?: 4543 1374 5089 4332')
@@ -306,14 +215,12 @@ const result = await agent.generate('Is this credit card number valid?: 4543 137
 if (result.tripwire) {
   console.error('Blocked:', result.tripwire.reason)
   console.error('Processor:', result.tripwire.processorId)
-  // Optional: check if retry was requested
-  console.error('Retry requested:', result.tripwire.retry)
-  // Optional: access additional metadata
-  console.error('Metadata:', result.tripwire.metadata)
 }
 ```
 
-#### `.stream()` example
+### With `stream()`
+
+Listen for `tripwire` chunks in the stream:
 
 ```typescript
 const stream = await agent.stream('Is this credit card number valid?: 4543 1374 5089 4332')
@@ -326,49 +233,95 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-In this case, the `reason` indicates that a credit card number was detected:
+## Speed up guardrails
 
-```text
-PII detected. Types: credit-card
-```
+Guardrail processors that use an LLM (moderation, PII detection, prompt injection) add latency to every request. Three techniques reduce this overhead.
 
-### Requesting retries
+### Run guardrails in parallel
 
-Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks:
+By default, processors run sequentially. Guardrails that only `block` (and never mutate messages) are independent and can run at the same time using a [workflow processor](https://mastra.ai/docs/agents/processors).
 
-```typescript
-export class QualityChecker implements Processor {
-  id = 'quality-checker'
+You can also mix `block` and `redact` strategies in a single parallel step. Map to the `redact` branch so its transformed messages carry forward.
 
-  async processOutputStep({ text, abort, retryCount }) {
-    const score = await evaluateQuality(text)
+For output guardrails, run `TokenLimiterProcessor` and `BatchPartsProcessor` sequentially _before_ the parallel step, and any `redact` processors that depend on each other sequentially _after_ it:
 
-    if (score < 0.7 && retryCount < 3) {
-      // Request retry with feedback for the LLM
-      abort('Response quality too low. Please be more specific.', {
-        retry: true,
-        metadata: { score },
-      })
-    }
+```typescript
+import { createWorkflow, createStep } from '@mastra/core/workflows'
+import {
+  ProcessorStepSchema,
+  PIIDetector,
+  ModerationProcessor,
+  SystemPromptScrubber,
+  TokenLimiterProcessor,
+  BatchPartsProcessor,
+} from '@mastra/core/processors'
 
-    return []
-  }
-}
+export const outputGuardrails = createWorkflow({
+  id: 'output-guardrails',
+  inputSchema: ProcessorStepSchema,
+  outputSchema: ProcessorStepSchema,
+})
+  // Sequential: limit tokens first, then batch stream chunks
+  .then(createStep(new TokenLimiterProcessor({ limit: 1000 })))
+  .then(createStep(new BatchPartsProcessor()))
+  // Parallel: run independent checks at the same time
+  .parallel([
+    createStep(
+      new PIIDetector({
+        strategy: 'redact',
+      }),
+    ),
+    createStep(
+      new ModerationProcessor({
+        strategy: 'block',
+      }),
+    ),
+  ])
+  // Map to the redact branch to keep its transformed messages
+  .map(async ({ inputData }) => {
+    return inputData['processor:pii-detector']
+  })
+  // Sequential: scrubber depends on previous redaction output
+  .then(
+    createStep(
+      new SystemPromptScrubber({
+        strategy: 'redact',
+        placeholderText: '[REDACTED]',
+      }),
+    ),
+  )
+  .commit()
 ```
 
-The `abort()` function accepts an optional second parameter with:
+See [workflows as processors](https://mastra.ai/docs/agents/processors) for more details on `.parallel()` and `.map()`.
 
-- `retry: true` - Request the LLM retry the step
-- `metadata: unknown` - Attach additional data for debugging/logging
+### Choose a fast model
 
-Use `retryCount` to track retry attempts and prevent infinite loops.
+Guardrail processors don't need your primary model. Use a small, fast model for classification tasks:
 
-## Custom processors
+```typescript
+const GUARDRAIL_MODEL = 'openai/gpt-5-nano'
+
+new ModerationProcessor({ model: GUARDRAIL_MODEL })
+new PIIDetector({ model: GUARDRAIL_MODEL })
+new PromptInjectionDetector({ model: GUARDRAIL_MODEL })
+```
 
-If the built-in processors don’t cover your needs, you can create your own by extending the `Processor` class.
+### Batch stream parts
+
+Output guardrails that implement `processOutputStream` run on every streamed chunk. Use `BatchPartsProcessor` _before_ heavier processors to combine chunks and reduce the number of LLM classification calls:
+
+```typescript
+outputProcessors: [
+  new BatchPartsProcessor({ batchSize: 10 }),
+  // Heavier processors now run on batched chunks instead of individual ones
+  new PIIDetector({ model: GUARDRAIL_MODEL, strategy: 'redact' }),
+  new ModerationProcessor({ model: GUARDRAIL_MODEL, strategy: 'block' }),
+]
+```
 
-Available examples:
+## Related
 
-- [Message Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-message-length-limiter)
-- [Response Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-length-limiter)
-- [Response Validator](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-validator)
+- [Processors](https://mastra.ai/docs/agents/processors): How processors work, execution order, custom processors, and retry mechanism
+- [`Processor` Interface](https://mastra.ai/reference/processors/processor-interface): API reference for the `Processor` interface
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors): Processors for message history, semantic recall, and working memory