> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# RegexFilterProcessor

`RegexFilterProcessor` は、コストゼロの正規表現パターンマッチングを適用し、Agent メッセージ内のコンテンツをフィルタリング、墨消し、またはブロックします。LLM 呼び出しは行われません。すべての検出は正規表現に基づきます。

一般的なパターン（PII、シークレット、URL）に対応する組み込みプリセットと、カスタム正規表現ルールをサポートします。入力、出力、または両方のフェーズに適用できます。

## 使用例

入力メッセージ内の PII をブロックします。

```typescript
import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'block',
  phase: 'input',
})
```

出力内のシークレットを墨消しします。

```typescript
import { RegexFilterProcessor } from '@mastra/core/processors'

const filter = new RegexFilterProcessor({
  presets: ['secrets'],
  strategy: 'redact',
  phase: 'output',
})
```

カスタムルール：

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

長いカスタム一致（固定長のシークレットや、終了区切り文字が届いた時点で初めて一致する値など）には、ストリーミングの持ち越しウィンドウを広げます。

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

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

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

**rules** (`RegexRule[]`): 適用するカスタム正規表現ルール。各ルールには名前、正規表現パターン、任意の置換文字列があります。

**rules.name** (`string`): ルールの表示名（一致レポートとエラーメッセージで使用）。

**rules.pattern** (`RegExp`): 照合する正規表現パターン。

**rules.replacement** (`string`): redact 方法で使用する置換文字列。デフォルトは '\[REDACTED]' です。

**presets** (`('pii' | 'secrets' | 'urls')[]`): 組み込みプリセットのカテゴリー。'pii' はメールアドレス、電話番号、SSN、クレジットカード番号、'secrets' は API キー、Bearer トークン、AWS キー、'urls' は HTTP/HTTPS URL に一致します。

**strategy** (`'block' | 'redact' | 'warn'`): パターン一致が見つかった場合の処理方法。'block' は TripWire エラーで中止、'redact' は一致したコンテンツを置換テキストに置き換え、'warn' は警告をログに記録しますがコンテンツを変更せず通過させます。 (Default: `'block'`)

**phase** (`'input' | 'output' | 'all'`): フィルターを適用するフェーズ。'input' は入力メッセージ、'output' は出力ストリームと結果、'all' は両方をフィルタリングします。 (Default: `'all'`)

**includeRedactedValues** (`boolean`): 各レポートエントリに墨消しされたテキストを含めます。これらの値は Processor が削除する対象データであるため、デフォルトでは無効です。 (Default: `false`)

**streamCarryoverSize** (`number`): チャンク境界をまたぐ一致をまとめて墨消しできるよう、ストリーミングの redact 処理がチャンク間で保持する末尾の文字数。デフォルト値には、すべての組み込みプリセットに十分な余裕があります。固定長のシークレットや終了区切り文字を持つ値など、完結するまでルールから一致を認識できず、その一致がウィンドウより長くなる可能性があるカスタムルールでは、この値を増やしてください。 (Default: `128`)

## 戻り値

**id** (`'regex-filter'`): Processor の識別子。

**name** (`'Regex Filter'`): Processor の表示名。

**processInput** (`(args: ProcessInputArgs) => ProcessInputResult`): 入力メッセージを設定済みのすべてのルールと照合します。strategy に応じて、ブロック、墨消し、または警告します。phase が output の場合はスキップされます。

**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null | undefined>`): ストリーミングの text-delta チャンクを設定済みのすべてのルールと照合します。phase が input の場合はスキップされます。

**processOutputResult** (`(args: ProcessOutputResultArgs) => ProcessorMessageResult`): 出力メッセージを設定済みのすべてのルールと照合します。strategy に応じて、ブロック、墨消し、または警告します。phase が input の場合はスキップされます。

## エラー動作

`block` 方法が有効な場合（デフォルト）、`RegexFilterProcessor` はいずれかのパターンが一致すると、`retry: false` の `TripWire` エラーをスローします。TripWire のメタデータには次が含まれます。

- `processorId`：`'regex-filter'`
- `matches`：`rule`、`match`（`'[REDACTED_MATCH]'` に墨消し）、`index` を持つ一致オブジェクトの配列
- `strategy`：`'block'`

## 組み込みプリセット

| プリセット     | パターン                          | デフォルトの置換                                    |
| --------- | ----------------------------- | ------------------------------------------- |
| `pii`     | メールアドレス、電話番号、SSN、クレジットカード番号   | `[EMAIL]`、`[PHONE]`、`[SSN]`、`[CREDIT_CARD]` |
| `secrets` | API キー、Bearer トークン、AWS アクセスキー | `[API_KEY]`、`[BEARER_TOKEN]`、`[AWS_KEY]`    |
| `urls`    | HTTP/HTTPS URL                | `[URL]`                                     |

## 墨消しの動作

各ルールは個別に照合されるため、2つのルールが重複するテキストに一致する場合があります。たとえば、区切り文字なしで記述されたカード番号は `phone` と `credit-card` の両方に一致します。重複する一致は1つの領域にまとめられ、最長の一致の置換値を使用して一度だけ置き換えられます。

```typescript
const filter = new RegexFilterProcessor({
  presets: ['pii'],
  strategy: 'redact',
})

// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
```

置換文字列では、`$1` または `$&` でキャプチャグループを参照できます。これらの参照が解決されるのは、パターンが一致したテキスト単体にも一致する、単一の一致の場合です。結合された領域の場合や、後読みまたは先読みで周囲に固定されたルールの場合、置換文字列はそのまま挿入されます。どちらの場合も領域は墨消しされます。

## 墨消しのレポート

`redact` 方法はテキストをその場で書き換えるため、後続処理からは変更内容を判別できません。記録するには `onViolation` を設定します。Processor は、墨消しされたメッセージ、メッセージ part、またはストリームチャンクごとに1回呼び出します。オフセットはそのテキスト片を基準とします。非同期コールバックは完了まで待機されます。監査先が利用できない場合でもリクエストが失敗しないよう、エラーは捕捉されます。

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

一致を含む各チャンクで実行される `processOutputStream` 内も含め、コールバックの完了を待機します。低速な監査先がストリーミングレスポンスを停止させないよう、コールバックは高速に保つか、処理をキューへ渡してください。コールバックを設定しない場合、`redact` 処理は同期のままです。

`block` 方法も同じコールバックを通じてレポートします。この場合、Processor runner が `TripWire` を捕捉したときにコールバックを呼び出すため、`detail` には以下の形式ではなく、[エラー動作](#error-behavior)で説明した Tripwire メタデータが入ります。

墨消しの `detail` は `RegexRedactionDetail` です。

**strategy** (`'redact'`): 墨消しレポートと block 方法のペイロードを区別します。

**phase** (`'processInput' | 'processOutputStream' | 'processOutputResult'`): 墨消しを適用した Processor メソッド。

**messageId** (`string`): テキストの取得元メッセージの ID。ストリームチャンクにはありません。

**partIndex** (`number`): テキスト以外の part も含むメッセージの parts 配列内で、墨消しされた part のインデックス。文字列コンテンツとストリームチャンクにはありません。

**redactions** (`RegexRedaction[]`): テキスト内の出現順に並んだ墨消し。

**redactions.rule** (`string`): 置換値が使用されたルールの名前。

**redactions.index** (`number`): テキスト内の墨消し範囲の開始オフセット。

**redactions.length** (`number`): 墨消し範囲の長さ。

**redactions.replacement** (`string`): 範囲を置き換えたテキスト。

**redactions.overlappingRules** (`string[]`): この範囲に一致したすべてのルール名。複数の一致が重複した場合のみ設定されます。

**redactions.value** (`string`): 墨消しされたテキスト。includeRedactedValues が有効な場合のみ設定されます。

デフォルトでは値を含めません。保護対象データを監査証跡へコピーすると、縮小するために導入した露出範囲を逆に広げることになります。`includeRedactedValues` は、保存先が元のデータと同等に保護されている場合に限り設定してください。同じ理由から、`block` 方法も一致したテキストを `TripWire` メタデータに含めません。