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

# RegexFilter프로세서

그만큼`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`): 각 보고서 항목에 삭제된 텍스트를 포함합니다. 해당 값은 프로세서가 제거하는 데이터이므로 기본적으로 비활성화됩니다. (Default: `false`)

**streamCarryoverSize** (`number`): 스트리밍 redact 경로가 청크 사이에서 보류하는 후행 문자 수입니다. 따라서 청크 경계에 걸쳐 나뉜 일치 항목도 전체가 삭제됩니다. 기본값은 모든 기본 제공 사전 설정을 넉넉하게 포괄합니다. 고정 길이 비밀 값이나 닫는 구분 기호가 있는 값처럼 일치가 완료될 때까지 규칙에 표시되지 않는 사용자 지정 규칙의 일치 항목이 이 창보다 길 수 있다면 값을 늘리세요. (Default: `128`)

## 보고

**id** (`'regex-filter'`): 프로세서 식별자입니다.

**name** (`'Regex Filter'`): 프로세서 표시 이름입니다.

**processInput** (`(args: ProcessInputArgs) => ProcessInputResult`): 구성된 모든 규칙을 기준으로 입력 메시지를 확인합니다. 전략에 따라 차단하거나 삭제하거나 경고합니다. phase가 output이면 건너뜁니다.

**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null | undefined>`): 구성된 모든 규칙을 기준으로 스트리밍 text-delta 청크를 확인합니다. phase가 input이면 건너뜁니다.

**processOutputResult** (`(args: ProcessOutputResultArgs) => ProcessorMessageResult`): 구성된 모든 규칙을 기준으로 출력 메시지를 확인합니다. 전략에 따라 차단하거나 삭제하거나 경고합니다. phase가 input이면 건너뜁니다.

## 오류 동작

`block` 전략이 활성화된 경우(기본값), 패턴이 하나라도 일치하면 `RegexFilterProcessor`가 `retry: false`인 `TripWire` 오류를 발생시킵니다. TripWire 메타데이터에는 다음 항목이 포함됩니다.

- `processorId`: `'regex-filter'`
- `matches`: `rule`, `match`(`'[REDACTED_MATCH]'`로 삭제됨), `index`를 포함하는 일치 객체의 배열
- `strategy`: `'block'`

## 내장된 사전 설정

| 프리셋       | 패턴                                               | 기본 교체                                          |
| --------- | ------------------------------------------------ | ---------------------------------------------- |
| `pii`     | Emails, phone numbers, SSNs, credit card numbers | `[EMAIL]`, `[PHONE]`, `[SSN]`, `[CREDIT_CARD]` |
| `secrets` | API keys, bearer tokens, AWS access keys         | `[API_KEY]`, `[BEARER_TOKEN]`, `[AWS_KEY]`     |
| `urls`    | HTTP/HTTPS URL                                   | `[URL]`                                        |

## 수정 동작

모든 규칙은 독립적으로 일치하므로 두 규칙이 겹치는 텍스트를 대상으로 할 수 있습니다. 예를 들어 구분 기호 없이 작성된 카드 번호는 `phone`과 `credit-card`에 모두 일치합니다. 겹치는 일치 항목은 하나의 영역으로 결합되고 가장 긴 일치 항목의 대체 문자열을 사용하여 한 번만 대체됩니다.

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

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

대체 문자열은 `$1` 또는 `$&`를 사용하여 캡처 그룹을 참조할 수 있습니다. 해당 참조는 패턴 자체로도 일치 텍스트와 일치하는 단일 일치 항목에서 해석됩니다. 결합된 영역이나 lookbehind 또는 lookahead를 사용하여 주변 텍스트에 고정된 규칙에서는 대체 문자열이 작성된 그대로 삽입됩니다. 어느 경우든 해당 영역은 삭제됩니다.

## 교정 보고

`redact` 전략은 텍스트를 제자리에서 다시 작성하므로 이후 처리 단계에서는 무엇이 변경되었는지 알 수 없습니다. 이를 기록하려면 `onViolation`을 할당하세요. 프로세서는 삭제된 메시지, 메시지 부분 또는 스트림 청크마다 한 번씩 이를 호출하며, 오프셋은 해당 텍스트 조각을 기준으로 합니다. 비동기 콜백의 완료를 기다리며, 감사 싱크를 사용할 수 없더라도 요청이 실패하지 않도록 오류를 포착합니다.

```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` 전략도 같은 콜백을 통해 보고합니다. 이 경우 프로세서 실행기가 `TripWire`를 포착할 때 콜백을 호출하므로 `detail`에는 아래 형식이 아니라 [오류 동작](#error-behavior)에 설명된 tripwire 메타데이터가 들어갑니다. `detail`편집의 경우`RegexRedactionDetail`:

**strategy** (`'redact'`): 삭제 보고서를 block 전략 페이로드와 구분합니다.

**phase** (`'processInput' | 'processOutputStream' | 'processOutputResult'`): 삭제를 적용한 프로세서 메서드입니다.

**messageId** (`string`): 텍스트가 유래한 메시지의 ID입니다. 스트림 청크에는 없습니다.

**partIndex** (`number`): 텍스트가 아닌 부분도 포함하는 메시지의 parts 배열에서 삭제된 부분의 인덱스입니다. 문자열 콘텐츠와 스트림 청크에는 없습니다.

**redactions** (`RegexRedaction[]`): 텍스트에 나타나는 순서대로 정렬된 삭제 항목입니다.

**redactions.rule** (`string`): 대체 문자열이 사용된 규칙의 이름입니다.

**redactions.index** (`number`): 텍스트에서 삭제된 범위의 시작 오프셋입니다.

**redactions.length** (`number`): 삭제된 범위의 길이입니다.

**redactions.replacement** (`string`): 해당 범위를 대체한 텍스트입니다.

**redactions.overlappingRules** (`string[]`): 이 범위와 일치한 모든 규칙의 이름입니다. 둘 이상이 겹친 경우에만 설정됩니다.

**redactions.value** (`string`): 삭제된 텍스트입니다. includeRedactedValues가 활성화된 경우에만 설정됩니다.

값은 기본적으로 생략됩니다. 보호 대상 데이터를 복사하는 감사 추적은 추가적인 노출 범위를 만듭니다. 대상이 원본만큼 안전하게 보호되는 경우에만 `includeRedactedValues`를 설정하세요. 같은 이유로 `block` 전략도 `TripWire` 메타데이터에서 일치한 텍스트를 제외합니다.