> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # RegexFilterProcessor `RegexFilterProcessor` applique une correspondance sans coût de motifs d'expressions régulières afin de filtrer, masquer ou bloquer le contenu des messages d'un Agent. Aucun appel de LLM n'est effectué. Toute la détection repose sur des expressions régulières. Il prend en charge des préréglages intégrés pour les motifs courants (PII, secrets et URL) ainsi que des règles d'expressions régulières personnalisées. Il peut être appliqué à l'entrée, à la sortie ou aux deux phases. ## Exemple d'utilisation Bloquez les PII dans les messages d'entrée : ```typescript import { RegexFilterProcessor } from '@mastra/core/processors' const filter = new RegexFilterProcessor({ presets: ['pii'], strategy: 'block', phase: 'input', }) ``` Masquez les secrets dans la sortie : ```typescript import { RegexFilterProcessor } from '@mastra/core/processors' const filter = new RegexFilterProcessor({ presets: ['secrets'], strategy: 'redact', phase: 'output', }) ``` Règles personnalisées : ```typescript import { RegexFilterProcessor } from '@mastra/core/processors' const filter = new RegexFilterProcessor({ rules: [{ name: 'internal-id', pattern: /INTERNAL-\d{6}/g, replacement: '[INTERNAL_ID]' }], strategy: 'redact', }) ``` Augmentez la fenêtre de report du streaming pour les longues correspondances personnalisées (par exemple, un secret de longueur fixe ou une valeur qui correspond uniquement lorsque son délimiteur de fermeture arrive) : ```typescript import { RegexFilterProcessor } from '@mastra/core/processors' const filter = new RegexFilterProcessor({ rules: [ { name: 'armored-key', pattern: /-----BEGIN KEY-----[A-Z]+-----END KEY-----/g, replacement: '[KEY]', }, ], strategy: 'redact', streamCarryoverSize: 256, }) ``` Associez-le à un Agent : ```typescript import { Agent } from '@mastra/core/agent' import { RegexFilterProcessor } from '@mastra/core/processors' const agent = new Agent({ id: 'my-agent', name: 'my-agent', model: 'openai/gpt-5-nano', inputProcessors: [ new RegexFilterProcessor({ presets: ['pii', 'secrets'], strategy: 'block', }), ], }) ``` ## Paramètres du constructeur **rules** (`RegexRule[]`): Règles d'expressions régulières personnalisées à appliquer. Chaque règle possède un nom, un motif d'expression régulière et une chaîne de remplacement facultative. **rules.name** (`string`): Nom d'affichage de la règle (utilisé dans les rapports de correspondance et les messages d'erreur). **rules.pattern** (`RegExp`): Motif d'expression régulière à rechercher. **rules.replacement** (`string`): Chaîne de remplacement de la stratégie redact. Utilise par défaut '\[REDACTED]'. **presets** (`('pii' | 'secrets' | 'urls')[]`): Catégories de préréglages intégrées. 'pii' correspond aux e-mails, numéros de téléphone, SSN et cartes de crédit. 'secrets' correspond aux clés d'API, tokens bearer et clés AWS. 'urls' correspond aux URL HTTP/HTTPS. **strategy** (`'block' | 'redact' | 'warn'`): Stratégie appliquée lors de la détection d'une correspondance. 'block' interrompt l'opération avec une erreur TripWire. 'redact' remplace le contenu correspondant par le texte de remplacement. 'warn' journalise un avertissement, mais transmet le contenu sans le modifier. (Default: `'block'`) **phase** (`'input' | 'output' | 'all'`): Phases auxquelles appliquer le filtre. 'input' filtre les messages d'entrée. 'output' filtre le flux et le résultat de sortie. 'all' filtre les deux. (Default: `'all'`) **includeRedactedValues** (`boolean`): Inclut le texte masqué dans chaque entrée du rapport. Désactivé par défaut, car ces valeurs sont précisément les données supprimées par le Processor. (Default: `false`) **streamCarryoverSize** (`number`): Nombre de caractères de fin conservés entre les chunks par le chemin redact du streaming, afin qu'une correspondance répartie sur une limite de chunk soit entièrement masquée. La valeur par défaut couvre largement tous les préréglages intégrés. Augmentez-la pour les règles personnalisées dont les correspondances restent invisibles jusqu'à leur achèvement, telles qu'un secret de longueur fixe ou une valeur dotée d'un délimiteur de fermeture, lorsque la correspondance peut dépasser la taille de la fenêtre. (Default: `128`) ## Valeur renvoyée **id** (`'regex-filter'`): Identifiant du Processor. **name** (`'Regex Filter'`): Nom d'affichage du Processor. **processInput** (`(args: ProcessInputArgs) => ProcessInputResult`): Vérifie les messages d'entrée par rapport à toutes les règles configurées. Bloque, masque ou avertit selon la stratégie. Ignoré lorsque la phase est output. **processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise`): Vérifie les chunks text-delta du streaming par rapport à toutes les règles configurées. Ignoré lorsque la phase est input. **processOutputResult** (`(args: ProcessOutputResultArgs) => ProcessorMessageResult`): Vérifie les messages de sortie par rapport à toutes les règles configurées. Bloque, masque ou avertit selon la stratégie. Ignoré lorsque la phase est input. ## Comportement en cas d'erreur Lorsque la stratégie `block` est active (par défaut), `RegexFilterProcessor` lève une erreur `TripWire` avec `retry: false` dès qu'un motif correspond. Les métadonnées TripWire comprennent : - `processorId`: `'regex-filter'` - `matches` : tableau d'objets de correspondance contenant `rule`, `match` (masqué sous la forme `'[REDACTED_MATCH]'`) et `index` - `strategy`: `'block'` ## Préréglages intégrés | Préréglage | Motifs | Remplacement par défaut | | ---------- | -------------------------------------------------------------- | ---------------------------------------------- | | `pii` | E-mails, numéros de téléphone, SSN, numéros de carte de crédit | `[EMAIL]`, `[PHONE]`, `[SSN]`, `[CREDIT_CARD]` | | `secrets` | Clés d'API, tokens bearer, clés d'accès AWS | `[API_KEY]`, `[BEARER_TOKEN]`, `[AWS_KEY]` | | `urls` | URL HTTP/HTTPS | `[URL]` | ## Comportement du masquage Chaque règle est recherchée indépendamment ; deux règles peuvent donc correspondre à des portions de texte qui se chevauchent. Par exemple, un numéro de carte écrit sans séparateurs correspond à la fois à `phone` et à `credit-card`. Les correspondances qui se chevauchent sont regroupées en une seule région et remplacées une seule fois au moyen du remplacement de la correspondance la plus longue. ```typescript const filter = new RegexFilterProcessor({ presets: ['pii'], strategy: 'redact', }) // "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today" ``` Une chaîne de remplacement peut référencer des groupes de capture au moyen de `$1` ou `$&`. Ces références sont résolues pour une correspondance unique dont le motif correspond également seul au texte détecté. Dans une région combinée, ou pour une règle ancrée sur son contexte avec un lookbehind ou un lookahead, la chaîne de remplacement est insérée telle quelle. Dans les deux cas, la région est masquée. ## Rapports de masquage La stratégie `redact` réécrit le texte sur place ; les étapes suivantes ne peuvent donc pas déterminer ce qui a changé. Affectez `onViolation` afin de l'enregistrer. Le Processor l'appelle une fois par message, partie de message ou chunk de flux masqué, et les offsets sont relatifs à cette portion de texte. Les callbacks asynchrones sont attendus et les erreurs interceptées, afin qu'une destination d'audit indisponible ne fasse pas échouer la requête. ```typescript import { RegexFilterProcessor, type RegexRedactionDetail } from '@mastra/core/processors' const filter = new RegexFilterProcessor({ presets: ['pii'], strategy: 'redact', }) filter.onViolation = async ({ detail }) => { const redaction = detail as RegexRedactionDetail for (const entry of redaction.redactions) { await auditLog.write({ phase: redaction.phase, messageId: redaction.messageId, rule: entry.rule, offset: entry.index, length: entry.length, }) } } ``` Le callback est attendu, y compris dans `processOutputStream`, où il s'exécute pour chaque chunk contenant une correspondance. Veillez à ce qu'il soit rapide, ou confiez le travail à une file d'attente, afin qu'une destination d'audit lente ne bloque pas une réponse en streaming. Si aucun callback n'est associé, le chemin `redact` reste synchrone. La stratégie `block` produit un rapport au moyen du même callback. Le Runner du Processor l'invoque lorsqu'il intercepte le `TripWire` ; `detail` contient donc les métadonnées TripWire décrites dans [Comportement en cas d'erreur](#error-behavior), et non la structure ci-dessous. Pour un masquage, `detail` est un `RegexRedactionDetail` : **strategy** (`'redact'`): Distingue un rapport de masquage du payload de la stratégie block. **phase** (`'processInput' | 'processOutputStream' | 'processOutputResult'`): Méthode du Processor qui a appliqué les masquages. **messageId** (`string`): Identifiant du message d'où provient le texte. Absent pour les chunks de flux. **partIndex** (`number`): Index de la partie masquée dans le tableau de parties du message, qui contient également des parties non textuelles. Absent pour le contenu sous forme de chaîne et les chunks de flux. **redactions** (`RegexRedaction[]`): Masquages dans leur ordre d'apparition dans le texte. **redactions.rule** (`string`): Nom de la règle dont le remplacement a été utilisé. **redactions.index** (`number`): Offset de début de la portion masquée dans le texte. **redactions.length** (`number`): Longueur de la portion masquée. **redactions.replacement** (`string`): Texte qui a remplacé la portion. **redactions.overlappingRules** (`string[]`): Noms de toutes les règles ayant correspondu à cette portion. Défini uniquement lorsque plusieurs correspondances se chevauchent. **redactions.value** (`string`): Texte masqué. Défini uniquement lorsque includeRedactedValues est activé. Les valeurs sont omises par défaut. Une piste d'audit qui copie les données qu'elle protège élargit l'exposition qu'elle devait réduire. Définissez `includeRedactedValues` uniquement lorsque la destination est aussi protégée que l'original, et notez que la stratégie `block` masque également le texte correspondant dans ses métadonnées `TripWire` pour la même raison.