PIIDetector

PIIDetector は、入力と出力の両方の処理に使用できる ハイブリッド Processor です。プライバシー規制への準拠に向けて、個人を特定できる情報（PII）を検出して秘匿化します。PII の種類を特定し、複数の秘匿化方法を含む柔軟な処理方法を提供することで、GDPR、CCPA、HIPAA などのプライバシー規制に準拠できるようにします。

使用例

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

コンストラクターパラメーター

options:

Options

PII の検出と秘匿化の設定オプション

Options

model:

MastraModelConfig

検出 Agent のモデル設定

detectionTypes?:

string[]

検出する PII の種類。指定しない場合はデフォルトの種類を使用します

threshold?:

number

フラグを付ける信頼度しきい値（0〜1）。いずれかのカテゴリースコアがこのしきい値を超えると、PII にフラグが付きます

strategy?:

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

PII を検出した場合の処理方法。'block' はエラーで拒否、'warn' は警告をログに記録して通過を許可、'filter' はフラグが付いたメッセージを削除、'redact' は PII を秘匿化した値に置き換えます

redactionMethod?:

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

PII の秘匿化方法。'mask' はアスタリスク、'hash' は SHA256 ハッシュに置き換え、'remove' は完全に削除、'placeholder' は種類を示すプレースホルダーに置き換えます

instructions?:

string

Agent に与えるカスタム検出指示。指定しない場合は検出対象の種類に基づくデフォルトの指示を使用します

includeDetections?:

boolean

検出の詳細をログに含めるかどうか。コンプライアンス監査やデバッグに役立ちます

lastMessageOnly?:

boolean

すべてのメッセージを確認せず、バッチ内の最新メッセージだけを検査するかどうか。長い Thread で以前の各メッセージに1回ずつ LLM 呼び出しが発生するのを防ぐために使用します。

preserveFormat?:

boolean

秘匿化時に PII の形式を維持するかどうか。true の場合、電話番号の ***-**-1234 のような構造を維持します

providerOptions?:

ProviderOptions

内部の検出 Agent に渡す Provider 固有のオプション。思考モデルの推論量など、モデルの動作を制御するために使用します（例：{ openai: { reasoningEffort: 'low' } }）

戻り値

id:

string

'pii-detector' に設定された Processor の識別子

name?:

string

任意の Processor 表示名

processInput:

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

LLM に送信する前に入力メッセージを処理し、PII を検出して秘匿化します

processOutputStream:

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

ストリーミング中に出力パーツを処理し、PII を検出して秘匿化します

詳細な使用例

入力処理

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

バッチ処理を使った出力処理

PIIDetector を出力 Processor として使用する場合は、パフォーマンスを最適化するために BatchPartsProcessor との併用を推奨します。BatchPartsProcessor はストリームチャンクをまとめてから PII Detector に渡し、検出に必要な LLM 呼び出し回数を減らします。

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

関連項目

• Guardrails