RegexFilter프로세서
그만큼RegexFilterProcessorAgent 메시지의 콘텐츠를 필터링, 수정 또는 차단하기 위해 무료 정규식 패턴 일치를 적용합니다. LLM 통화는 이루어지지 않습니다. 모든 탐지는 정규식 기반입니다.
일반 패턴(PII, 비밀, URL) 및 사용자 정의 정규식 규칙에 대한 내장 사전 설정을 지원합니다. 입력, 출력 또는 두 단계 모두에 적용할 수 있습니다.
사용예사용예에 대한 직접 링크
입력 메시지에서 PII를 차단합니다.
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
presets: ['pii'],
strategy: 'block',
phase: 'input',
})
출력에서 비밀을 수정합니다.
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
presets: ['secrets'],
strategy: 'redact',
phase: 'output',
})
맞춤 규칙:
import { RegexFilterProcessor } from '@mastra/core/processors'
const filter = new RegexFilterProcessor({
rules: [{ name: 'internal-id', pattern: /INTERNAL-\d{6}/g, replacement: '[INTERNAL_ID]' }],
strategy: 'redact',
})
긴 사용자 지정 일치(예: 고정 길이 비밀 또는 닫는 구분 기호가 도착한 후에만 일치하는 값):
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에 연결:
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?:
name:
pattern:
replacement?:
presets?:
strategy?:
phase?:
includeRedactedValues?:
streamCarryoverSize?:
보고보고에 대한 직접 링크
id:
name:
processInput:
processOutputStream:
processOutputResult:
오류 동작오류 동작에 대한 직접 링크
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에 모두 일치합니다. 겹치는 일치 항목은 하나의 영역으로 결합되고 가장 긴 일치 항목의 대체 문자열을 사용하여 한 번만 대체됩니다.
const filter = new RegexFilterProcessor({
presets: ['pii'],
strategy: 'redact',
})
// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
대체 문자열은 $1 또는 $&를 사용하여 캡처 그룹을 참조할 수 있습니다. 해당 참조는 패턴 자체로도 일치 텍스트와 일치하는 단일 일치 항목에서 해석됩니다. 결합된 영역이나 lookbehind 또는 lookahead를 사용하여 주변 텍스트에 고정된 규칙에서는 대체 문자열이 작성된 그대로 삽입됩니다. 어느 경우든 해당 영역은 삭제됩니다.
교정 보고교정 보고에 대한 직접 링크
redact 전략은 텍스트를 제자리에서 다시 작성하므로 이후 처리 단계에서는 무엇이 변경되었는지 알 수 없습니다. 이를 기록하려면 onViolation을 할당하세요. 프로세서는 삭제된 메시지, 메시지 부분 또는 스트림 청크마다 한 번씩 이를 호출하며, 오프셋은 해당 텍스트 조각을 기준으로 합니다. 비동기 콜백의 완료를 기다리며, 감사 싱크를 사용할 수 없더라도 요청이 실패하지 않도록 오류를 포착합니다.
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에는 아래 형식이 아니라 오류 동작에 설명된 tripwire 메타데이터가 들어갑니다.
detail편집의 경우RegexRedactionDetail:
strategy:
phase:
messageId?:
partIndex?:
redactions:
rule:
index:
length:
replacement:
overlappingRules?:
value?:
값은 기본적으로 생략됩니다. 보호 대상 데이터를 복사하는 감사 추적은 추가적인 노출 범위를 만듭니다. 대상이 원본만큼 안전하게 보호되는 경우에만 includeRedactedValues를 설정하세요. 같은 이유로 block 전략도 TripWire 메타데이터에서 일치한 텍스트를 제외합니다.