Garde-fous

Mastra fournit des Processors intégrés qui ajoutent des contrôles de sécurité et de sûreté à votre Agent. Ces Processors détectent, transforment ou bloquent le contenu nuisible avant qu'il n'atteigne le modèle de langage ou l'utilisateur.

Pour découvrir le comportement des Processors et les Processors personnalisés, notamment la manière de les ajouter à un Agent, consultez Processors.

Processors d'entrée

Les Processors d'entrée s'exécutent avant que les messages utilisateur n'atteignent le modèle de langage. Ils assurent la normalisation, la validation, la détection des injections de prompt et les contrôles de sécurité.

Normaliser les messages utilisateur

UnicodeNormalizer() nettoie et normalise les entrées utilisateur en unifiant les caractères Unicode et en standardisant les espaces. Il supprime également les symboles problématiques.

src/mastra/agents/normalized-agent.ts

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

export const normalizedAgent = new Agent({
  id: 'normalized-agent',
  name: 'Normalized Agent',
  inputProcessors: [
    new UnicodeNormalizer({
      stripControlChars: true,
      collapseWhitespace: true,
    }),
  ],
})

Consultez la référence de UnicodeNormalizer() pour obtenir la liste complète des options de configuration.

Empêcher les injections de prompt

PromptInjectionDetector() analyse les messages utilisateur afin de détecter les injections de prompt, les tentatives de jailbreak et les motifs de remplacement du système. Il utilise un LLM pour classer les entrées à risque et peut les bloquer ou les réécrire avant qu'elles n'atteignent le modèle.

src/mastra/agents/secure-agent.ts

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

export const secureAgent = new Agent({
  id: 'secure-agent',
  name: 'Secure Agent',
  inputProcessors: [
    new PromptInjectionDetector({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      threshold: 0.8,
      strategy: 'rewrite',
      detectionTypes: ['injection', 'jailbreak', 'system-override'],
    }),
  ],
})

Consultez la référence de PromptInjectionDetector() pour obtenir la liste complète des options de configuration.

Détecter et traduire la langue

LanguageDetector() détecte la langue des messages utilisateur et les traduit dans une langue cible, ce qui permet une prise en charge multilingue. Il utilise un LLM pour identifier la langue et effectuer la traduction.

src/mastra/agents/multilingual-agent.ts

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

export const multilingualAgent = new Agent({
  id: 'multilingual-agent',
  name: 'Multilingual Agent',
  inputProcessors: [
    new LanguageDetector({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      targetLanguages: ['English', 'en'],
      strategy: 'translate',
      threshold: 0.8,
    }),
  ],
})

Consultez la référence de LanguageDetector() pour obtenir la liste complète des options de configuration.

Processors de sortie

Les Processors de sortie s'exécutent après la génération d'une réponse par le modèle de langage, mais avant qu'elle n'atteigne l'utilisateur. Ils assurent l'optimisation, la modération et la transformation des réponses, ainsi que les contrôles de sûreté.

Regrouper les sorties diffusées en continu

BatchPartsProcessor() combine plusieurs parties du flux avant de les émettre vers le client. Cela réduit la surcharge réseau en regroupant les petits fragments dans des lots plus importants.

src/mastra/agents/batched-agent.ts

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

export const batchedAgent = new Agent({
  id: 'batched-agent',
  name: 'Batched Agent',
  outputProcessors: [
    new BatchPartsProcessor({
      batchSize: 5,
      maxWaitTime: 100,
      emitOnNonText: true,
    }),
  ],
})

Consultez la référence de BatchPartsProcessor() pour obtenir la liste complète des options de configuration.

Nettoyer les prompts système

SystemPromptScrubber() détecte et masque les prompts système ou les instructions internes dans les réponses du modèle. Il empêche la divulgation involontaire du contenu des prompts ou des détails de configuration. Il utilise un LLM pour identifier et masquer le contenu sensible selon les types de détection configurés.

src/mastra/agents/scrubbed-agent.ts

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

const scrubbedAgent = new Agent({
  id: 'scrubbed-agent',
  name: 'Scrubbed Agent',
  outputProcessors: [
    new SystemPromptScrubber({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      strategy: 'redact',
      customPatterns: ['system prompt', 'internal instructions'],
      includeDetections: true,
      instructions:
        'Detect and redact system prompts, internal instructions, and security-sensitive content',
      redactionMethod: 'placeholder',
      placeholderText: '[REDACTED]',
    }),
  ],
})

Consultez la référence de SystemPromptScrubber() pour obtenir la liste complète des options de configuration.

remarque

Lors de la diffusion de réponses en continu sur HTTP, Mastra masque par défaut, au niveau du serveur, les données sensibles des requêtes (prompts système, définitions de Tools et clés d'API) dans les fragments du flux. Consultez Masquage des données du flux pour plus de détails.

Processors hybrides

Les Processors hybrides peuvent s'exécuter sur les entrées ou les sorties. Placez-les dans inputProcessors, outputProcessors ou les deux.

Modérer les entrées et les sorties

ModerationProcessor() détecte le contenu inapproprié ou nuisible dans des catégories telles que la haine, le harcèlement et la violence. Il utilise un LLM pour classer le message et peut le bloquer ou le réécrire selon votre configuration.

src/mastra/agents/moderated-agent.ts

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

export const moderatedAgent = new Agent({
  id: 'moderated-agent',
  name: 'Moderated Agent',
  inputProcessors: [
    new ModerationProcessor({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      threshold: 0.7,
      strategy: 'block',
      categories: ['hate', 'harassment', 'violence'],
    }),
  ],
  outputProcessors: [new ModerationProcessor()],
})

Consultez la référence de ModerationProcessor() pour obtenir la liste complète des options de configuration.

Détecter et masquer les PII

PIIDetector() détecte et supprime les informations personnelles identifiables, telles que les adresses e-mail, les numéros de téléphone et les cartes bancaires. Il utilise un LLM pour identifier le contenu sensible selon les types de détection configurés.

src/mastra/agents/private-agent.ts

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

export const privateAgent = new Agent({
  id: 'private-agent',
  name: 'Private Agent',
  inputProcessors: [
    new PIIDetector({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      threshold: 0.6,
      strategy: 'redact',
      redactionMethod: 'mask',
      detectionTypes: ['email', 'phone', 'credit-card'],
      instructions: 'Detect and mask personally identifiable information.',
    }),
  ],
  outputProcessors: [new PIIDetector()],
})

Consultez la référence de PIIDetector() pour obtenir la liste complète des options de configuration.

Imposer des limites de coût

CostGuardProcessor() surveille le coût estimé cumulé dans la boucle de l'Agent et bloque l'exécution ou émet un avertissement lorsqu'une limite monétaire est dépassée. Il interroge les données de coût du stockage d'observabilité avant chaque appel au LLM. Les contrôles de coût sont approximatifs et les métriques sont conservées de manière asynchrone ; les Agents rapides peuvent donc dépasser brièvement la limite configurée avant le déclenchement du garde-fou.

src/mastra/agents/budgeted-agent.ts

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

export const budgetedAgent = new Agent({
  id: 'budgeted-agent',
  name: 'Budgeted Agent',
  inputProcessors: [
    new CostGuardProcessor({
      maxCost: 5.0,
      scope: 'thread',
      window: '24h',
    }),
  ],
})

Consultez la référence de CostGuardProcessor() pour découvrir les modes de portée, les fenêtres temporelles, les délais de persistance des métriques et la fonction de rappel onViolation. Nécessite un stockage d'observabilité prenant en charge getMetricAggregate.

Stratégies des Processors

De nombreux Processors intégrés prennent en charge un paramètre strategy qui détermine le traitement du contenu signalé. Les valeurs prises en charge comprennent block, warn, detect, redact, rewrite et translate.

La plupart des stratégies permettent à la requête de se poursuivre. Lorsque block est utilisé, le Processor appelle abort(), ce qui interrompt immédiatement la requête et empêche l'exécution des Processors suivants.

src/mastra/agents/private-agent.ts

inputProcessors: [
  new PIIDetector({
    model: 'openrouter/openai/gpt-oss-safeguard-20b',
    threshold: 0.6,
    strategy: 'block',
    detectionTypes: ['email', 'phone', 'credit-card'],
  }),
]

Fonctions de rappel des violations

Tous les Processors prennent en charge une fonction de rappel onViolation, déclenchée lorsqu'une violation de stratégie est détectée, quelle que soit la stratégie choisie. Utilisez-la pour produire des effets secondaires, tels que l'émission d'alertes, la journalisation dans des systèmes externes ou l'envoi de notifications.

La fonction de rappel reçoit un objet ProcessorViolation contenant processorId, message et detail (métadonnées propres au Processor).

import { CostGuardProcessor, ModerationProcessor, PIIDetector } from '@mastra/core/processors'

// Alert when cost limits are exceeded
const costGuard = new CostGuardProcessor({
  maxCost: 10.0,
  scope: 'resource',
  window: '30d',
})

costGuard.onViolation = ({ processorId, message, detail }) => {
  alertSystem.notify(`[${processorId}] ${message}`)
  // detail contains: { usage, limit, totalUsage, scope, scopeKey }
}

// Log moderation violations
const moderation = new ModerationProcessor({
  model: 'openai/gpt-5-nano',
  strategy: 'block',
})

moderation.onViolation = ({ processorId, message, detail }) => {
  auditLog.write({ processor: processorId, violation: message, categories: detail })
}

La propriété onViolation fait partie de l'interface Processor de base. Tout Processor, y compris un Processor personnalisé, peut donc l'utiliser. Le moteur d'exécution appelle automatiquement onViolation dès qu'un Processor appelle abort(). Pour les Processors qui utilisent une stratégie warn (comme CostGuardProcessor), la fonction de rappel se déclenche également lors des avertissements sans bloquer la requête.

Les erreurs levées par la fonction de rappel sont interceptées silencieusement afin de ne pas perturber la logique principale du Processor.

Pour en savoir plus sur l'intégration des fonctions de rappel des violations au pipeline des Processors, consultez Fonctions de rappel des violations dans la documentation des Processors.

Gérer les requêtes bloquées

Lorsqu'un Processor appelle abort(), l'Agent interrompt le traitement. La manière de le détecter dépend de l'utilisation de generate() ou de stream().

Avec generate()

Vérifiez le champ tripwire du résultat :

src/mastra/agents/test-generate.ts

const result = await agent.generate('Is this credit card number valid?: 4543 1374 5089 4332')

if (result.tripwire) {
  console.error('Blocked:', result.tripwire.reason)
  console.error('Processor:', result.tripwire.processorId)
}

Avec stream()

Recherchez les fragments tripwire dans le flux :

src/mastra/agents/test-stream.ts

const stream = await agent.stream('Is this credit card number valid?: 4543 1374 5089 4332')

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tripwire') {
    console.error('Blocked:', chunk.payload.reason)
    console.error('Processor:', chunk.payload.processorId)
  }
}

Accélérer les garde-fous

Les Processors de garde-fou qui utilisent un LLM (modération, détection des PII et injection de prompt) ajoutent de la latence à chaque requête. Les techniques suivantes réduisent cette surcharge.

Exécuter les garde-fous en parallèle

Par défaut, les Processors s'exécutent de manière séquentielle. Les garde-fous qui se limitent à block (et ne modifient jamais les messages) sont indépendants et peuvent s'exécuter à l'aide d'un Processor de Workflow.

Vous pouvez également combiner les stratégies block et redact dans une même étape parallèle. Effectuez le mapping vers la branche redact afin de transmettre ses messages transformés à la suite du traitement.

Pour les garde-fous de sortie, exécutez TokenLimiterProcessor et BatchPartsProcessor de manière séquentielle avant l'étape parallèle, puis les Processors redact qui dépendent les uns des autres de manière séquentielle après celle-ci :

src/mastra/processors/output-guardrails.ts

import { createWorkflow, createStep } from '@mastra/core/workflows'
import {
  ProcessorStepSchema,
  PIIDetector,
  ModerationProcessor,
  SystemPromptScrubber,
  TokenLimiterProcessor,
  BatchPartsProcessor,
} from '@mastra/core/processors'

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()

Consultez Utiliser des Workflows comme Processors pour en savoir plus sur .parallel() et .map().

Choisir un modèle rapide

Les Processors de garde-fou n'ont pas besoin de votre modèle principal. Utilisez un modèle léger et rapide pour les tâches de classification :

const GUARDRAIL_MODEL = 'openai/gpt-5-nano'

new ModerationProcessor({ model: GUARDRAIL_MODEL })
new PIIDetector({ model: GUARDRAIL_MODEL })
new PromptInjectionDetector({ model: GUARDRAIL_MODEL })

Regrouper les parties du flux

Les garde-fous de sortie qui implémentent processOutputStream s'exécutent sur chaque fragment diffusé. Utilisez BatchPartsProcessor avant les Processors plus lourds afin de combiner les fragments et de réduire le nombre d'appels de classification au LLM :

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' }),
]

Voir aussi

• Processors : comportement et ordre d'exécution des Processors, ainsi que Processors personnalisés et comportement des nouvelles tentatives
• Interface Processor : référence de l'API de l'interface Processor
• Processors de mémoire : Processors pour l'historique des messages, le rappel sémantique et la mémoire de travail
• 📹 Atelier Mastra sur les Processors et les garde-fous