PIIDetector

PIIDetector est un Processor hybride qui peut traiter les entrées comme les sorties afin de détecter et de masquer les données personnelles identifiables (PII), conformément aux exigences de confidentialité. Ce Processor contribue à protéger la confidentialité en identifiant les types de PII et en proposant des stratégies flexibles pour les gérer, notamment plusieurs méthodes de masquage assurant la conformité au RGPD, au CCPA, à la HIPAA et aux autres réglementations relatives à la confidentialité.

Exemple d’utilisation

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

const processor = new PIIDetector({
  model: 'openrouter/openai/gpt-oss-safeguard-20b',
  threshold: 0.6,
  strategy: 'redact',
  detectionTypes: ['email', 'phone', 'credit-card', 'ssn'],
  lastMessageOnly: true,
})

Paramètres du constructeur

options:

Options

Options de configuration de la détection et du masquage des PII

Options

model:

MastraModelConfig

Configuration du modèle de l’Agent de détection

detectionTypes?:

string[]

Types de PII à détecter. S’ils ne sont pas indiqués, les types par défaut sont utilisés

threshold?:

number

Seuil de confiance du signalement (0 à 1). Une PII est signalée si le score d’une catégorie dépasse ce seuil

strategy?:

'block' | 'warn' | 'filter' | 'redact'

Stratégie appliquée lorsqu’une PII est détectée : 'block' la rejette avec une erreur, 'warn' enregistre un avertissement mais la laisse passer, 'filter' supprime les messages signalés et 'redact' remplace les PII par des versions masquées

redactionMethod?:

'mask' | 'hash' | 'remove' | 'placeholder'

Méthode de masquage des PII : 'mask' les remplace par des astérisques, 'hash' par un hash SHA256, 'remove' les supprime entièrement et 'placeholder' les remplace par un placeholder indiquant leur type

instructions?:

string

Instructions de détection personnalisées destinées à l’Agent. Si elles ne sont pas fournies, les instructions par défaut fondées sur les types de détection sont utilisées

includeDetections?:

boolean

Indique si les détails de détection doivent être inclus dans les logs. Utile pour les audits de conformité et le débogage

lastMessageOnly?:

boolean

Indique si seul le message le plus récent du lot doit être inspecté, au lieu de vérifier chaque message. Utilisez cette option pour éviter un appel au LLM pour chaque ancien message des longs fils.

preserveFormat?:

boolean

Indique si le format des PII doit être conservé pendant le masquage. Lorsque cette option vaut true, la structure des numéros de téléphone, telle que ***-**-1234, est préservée

providerOptions?:

ProviderOptions

Options propres au Provider transmises à l’Agent de détection interne. Utilisez-les pour contrôler le comportement du modèle, par exemple l’effort de raisonnement des modèles de réflexion (par exemple, { openai: { reasoningEffort: 'low' } })

Valeur renvoyée

id:

string

Identifiant du Processor défini sur 'pii-detector'

name?:

string

Nom d’affichage facultatif du Processor

processInput:

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

Traite les messages d’entrée afin de détecter et de masquer les PII avant de les envoyer au LLM

processOutputStream:

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

Traite les parties de la sortie diffusée afin de détecter et de masquer les PII pendant le streaming

Exemple d’utilisation avancée

Traitement des entrées

src/mastra/agents/private-agent.ts

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

export const agent = new Agent({
  id: 'private-agent',
  name: 'private-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [
    new PIIDetector({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      detectionTypes: ['email', 'phone', 'credit-card', 'ssn'],
      threshold: 0.6,
      strategy: 'redact',
      redactionMethod: 'mask',
      instructions:
        'Detect and redact personally identifiable information while preserving message intent',
      includeDetections: true,
      preserveFormat: true,
    }),
  ],
})

Traitement des sorties par lots

Lorsque vous utilisez PIIDetector comme Processor de sortie, il est recommandé de l’associer à BatchPartsProcessor afin d’optimiser les performances. BatchPartsProcessor regroupe les segments du flux avant de les transmettre au détecteur de PII, ce qui réduit le nombre d’appels au LLM nécessaires à la détection.

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

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

export const agent = new Agent({
  id: 'output-pii-agent',
  name: 'output-pii-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 PII detection on batched content
    new PIIDetector({
      model: 'openrouter/openai/gpt-oss-safeguard-20b',
      strategy: 'redact',
    }),
  ],
})

Voir aussi

• Guardrails