护栏

🌐 Guardrails

代理使用处理器对输入和输出应用安全控制。它们在每次交互之前或之后运行，为你提供一种在信息在用户和代理之间传递时进行审核、转换或阻止的方法。

🌐 Agents use processors to apply guardrails to inputs and outputs. They run before or after each interaction, giving you a way to review, transform, or block information as it passes between the user and the agent.

处理器可以配置为：

🌐 Processors can be configured as:

• inputProcessors：在消息到达语言模型之前应用。
• outputProcessors：应用于在返回给用户之前的响应。

一些处理器是_混合型_的，这意味着它们可以根据逻辑应应用的位置，与inputProcessors或outputProcessors一起使用。

🌐 Some processors are hybrid, meaning they can be used with either inputProcessors or outputProcessors, depending on where the logic should be applied.

何时使用处理器

🌐 When to use processors

使用处理器进行内容审查、提示注入防护、响应清理、消息转换以及其他与安全相关的控制。Mastra 提供了多种内置的输入和输出处理器，以满足常见的使用需求。

🌐 Use processors for content moderation, prompt injection prevention, response sanitization, message transformation, and other security-related controls. Mastra provides several built-in input and output processors for common use cases.

向代理添加处理器

🌐 Adding processors to an agent

导入并实例化相关的处理器类，然后使用 inputProcessors 或 outputProcessors 选项将其传递给代理的配置：

🌐 Import and instantiate the relevant processor class, and pass it to your agent’s configuration using either the inputProcessors or outputProcessors option:

src/mastra/agents/moderated-agent.ts

import { Agent } from "@mastra/core/agent";
import { ModerationProcessor } from "@mastra/core/processors";

export const moderatedAgent = new Agent({
  id: "moderated-agent",
  name: "Moderated Agent",
  instructions: "You are a helpful assistant",
  model: "openai/gpt-5.1",
  inputProcessors: [
    new ModerationProcessor({
      model: "openrouter/openai/gpt-oss-safeguard-20b",
      categories: ["hate", "harassment", "violence"],
      threshold: 0.7,
      strategy: "block",
      instructions: "Detect and flag inappropriate content in user messages",
    }),
  ],
});

输入处理器

🌐 Input processors

输入处理器在用户消息到达语言模型之前应用。它们对于规范化、验证、内容审核、提示注入检测和安全检查非常有用。

🌐 Input processors are applied before user messages reach the language model. They are useful for normalization, validation, content moderation, prompt injection detection, and security checks.

规范用户消息

🌐 Normalizing user messages

UnicodeNormalizer 是一个输入处理器，通过统一 Unicode 字符、标准化空白字符和删除问题符号来清理和规范用户输入，从而使大型语言模型（LLM）更好地理解用户消息。

🌐 The UnicodeNormalizer is an input processor that cleans and normalizes user input by unifying Unicode characters, standardizing whitespace, and removing problematic symbols, allowing the LLM to better understand user messages.

src/mastra/agents/normalized-agent.ts

import { UnicodeNormalizer } from "@mastra/core/processors";

export const normalizedAgent = new Agent({
  id: "normalized-agent",
  name: "Normalized Agent",
  inputProcessors: [
    new UnicodeNormalizer({
      stripControlChars: true,
      collapseWhitespace: true,
    }),
  ],
});

info

访问 UnicodeNormalizer 获取完整的配置选项列表。

🌐 Visit UnicodeNormalizer for a full list of configuration options.

防止提示注入

🌐 Preventing prompt injection

PromptInjectionDetector 是一个输入处理器，它会扫描用户消息以检测提示注入、越狱尝试和系统覆盖模式。它使用大型语言模型（LLM）对存在风险的输入进行分类，并可以在输入到达模型之前阻止或重写这些内容。

🌐 The PromptInjectionDetector is an input processor that scans user messages for prompt injection, jailbreak attempts, and system override patterns. It uses an LLM to classify risky input and can block or rewrite it before it reaches the model.

src/mastra/agents/secure-agent.ts

import { PromptInjectionDetector } from "@mastra/core/processors";

export const secureAgent = new Agent({
  id: "secure-agent",
  name: "Secure Agent",
  inputProcessors: [
    new PromptInjectionDetector({
      model: "openrouter/openai/gpt-oss-safeguard-20b",
      threshold: 0.8,
      strategy: "rewrite",
      detectionTypes: ["injection", "jailbreak", "system-override"],
    }),
  ],
});

info

访问 PromptInjectionDetector 查看完整的配置选项列表。

🌐 Visit PromptInjectionDetector for a full list of configuration options.

检测和翻译语言

🌐 Detecting and translating language

LanguageDetector 是一个输入处理器，可以检测并将用户消息翻译成目标语言，实现多语言支持，同时保持交互一致性。它使用大型语言模型（LLM）来识别语言并执行翻译。

🌐 The LanguageDetector is an input processor that detects and translates user messages into a target language, enabling multilingual support while maintaining consistent interaction. It uses an LLM to identify the language and perform the translation.

src/mastra/agents/multilingual-agent.ts

import { LanguageDetector } from "@mastra/core/processors";

export const multilingualAgent = new Agent({
  id: "multilingual-agent",
  name: "Multilingual Agent",
  inputProcessors: [
    new LanguageDetector({
      model: "openrouter/openai/gpt-oss-safeguard-20b",
      targetLanguages: ["English", "en"],
      strategy: "translate",
      threshold: 0.8,
    }),
  ],
});

info

访问 LanguageDetector 获取完整的配置选项列表。

🌐 Visit LanguageDetector for a full list of configuration options.

输出处理器

🌐 Output processors

输出处理器在语言模型生成回应之后、返回给用户之前应用。它们对于回应优化、内容审核、转换以及实现安全控制非常有用。

🌐 Output processors are applied after the language model generates a response, but before it is returned to the user. They are useful for response optimization, moderation, transformation, and applying safety controls.

批处理流式输出

🌐 Batching streamed output

BatchPartsProcessor 是一个输出处理器，它在将多个流部分发送给客户端之前将它们合并。这可以减少网络开销，并通过将小块数据整合成更大的批次来改善用户体验。

🌐 The BatchPartsProcessor is an output processor that combines multiple stream parts before emitting them to the client. This reduces network overhead and improves the user experience by consolidating small chunks into larger batches.

src/mastra/agents/batched-agent.ts

import { BatchPartsProcessor } from "@mastra/core/processors";

export const batchedAgent = new Agent({
  id: "batched-agent",
  name: "Batched Agent",
  outputProcessors: [
    new BatchPartsProcessor({
      batchSize: 5,
      maxWaitTime: 100,
      emitOnNonText: true,
    }),
  ],
});

info

访问 BatchPartsProcessor 以查看完整的配置选项列表。

🌐 Visit BatchPartsProcessor for a full list of configuration options.

限制令牌使用

🌐 Limiting token usage

TokenLimiterProcessor 是一个输出处理器，用于限制模型响应中的令牌数量。它通过在超出限制时截断或阻止消息来帮助管理成本和性能。

🌐 The TokenLimiterProcessor is an output processor that limits the number of tokens in model responses. It helps manage cost and performance by truncating or blocking messages when the limit is exceeded.

src/mastra/agents/limited-agent.ts

import { TokenLimiterProcessor } from "@mastra/core/processors";

export const limitedAgent = new Agent({
  id: "limited-agent",
  name: "Limited Agent",
  outputProcessors: [
    new TokenLimiterProcessor({
      limit: 1000,
      strategy: "truncate",
      countMode: "cumulative",
    }),
  ],
});

info

访问 TokenLimiterProcessor 以查看完整的配置选项列表。

🌐 Visit TokenLimiterProcessor for a full list of configuration options.

清理系统提示

🌐 Scrubbing system prompts

SystemPromptScrubber 是一个输出处理器，用于检测并编辑模型响应中的系统提示或其他内部指令。它有助于防止意外泄露提示内容或配置详情，从而降低安全风险。它使用大型语言模型（LLM）根据配置的检测类型识别并编辑敏感内容。

🌐 The SystemPromptScrubber is an output processor that detects and redacts system prompts or other internal instructions from model responses. It helps prevent unintended disclosure of prompt content or configuration details that could introduce security risks. It uses an LLM to identify and redact sensitive content based on configured detection types.

src/mastra/agents/scrubbed-agent.ts

import { SystemPromptScrubber } from "@mastra/core/processors";

const scrubbedAgent = new Agent({
  id: "scrubbed-agent",
  name: "Scrubbed Agent",
  outputProcessors: [
    new SystemPromptScrubber({
      model: "openrouter/openai/gpt-oss-safeguard-20b",
      strategy: "redact",
      customPatterns: ["system prompt", "internal instructions"],
      includeDetections: true,
      instructions:
        "Detect and redact system prompts, internal instructions, and security-sensitive content",
      redactionMethod: "placeholder",
      placeholderText: "[REDACTED]",
    }),
  ],
});

info

访问 SystemPromptScrubber 查看完整的配置选项列表。

🌐 Visit SystemPromptScrubber for a full list of configuration options.

note

在通过 HTTP 流式传输响应时，Mastra 默认会在服务器级别从流块中编辑敏感请求数据（系统提示、工具定义、API 密钥）。详情请参见 流数据编辑。

混合处理器

🌐 Hybrid processors

混合处理器可以在消息发送到语言模型之前或在响应返回给用户之前使用。它们对内容审核和个人识别信息（PII）脱敏等任务非常有用。

🌐 Hybrid processors can be applied either before messages are sent to the language model or before responses are returned to the user. They are useful for tasks like content moderation and PII redaction.

调节输入和输出

🌐 Moderating input and output

ModerationProcessor 是一种混合处理器，可以检测仇恨、骚扰和暴力等类别的不当或有害内容。它可以用于管理用户输入或模型输出，具体取决于应用场景。它使用大型语言模型（LLM）来分类信息，并可以根据你的配置阻止或重写内容。

🌐 The ModerationProcessor is a hybrid processor that detects inappropriate or harmful content across categories like hate, harassment, and violence. It can be used to moderate either user input or model output, depending on where it's applied. It uses an LLM to classify the message and can block or rewrite it based on your configuration.

src/mastra/agents/moderated-agent.ts

import { ModerationProcessor } from "@mastra/core/processors";

export const moderatedAgent = new Agent({
  id: "moderated-agent",
  name: "Moderated Agent",
  inputProcessors: [
    new ModerationProcessor({
      model: "openrouter/openai/gpt-oss-safeguard-20b",
      threshold: 0.7,
      strategy: "block",
      categories: ["hate", "harassment", "violence"],
    }),
  ],
  outputProcessors: [
    new ModerationProcessor(),
  ],
});

info

访问 ModerationProcessor 查看完整的配置选项列表。

🌐 Visit ModerationProcessor for a full list of configuration options.

检测和编辑个人身份信息

🌐 Detecting and redacting PII

PIIDetector 是一种混合处理器，用于检测和移除个人可识别信息，如电子邮件、电话号码和信用卡。它可以根据使用位置对用户输入或模型输出进行编辑。它使用大型语言模型（LLM）根据配置的检测类型识别敏感内容。

🌐 The PIIDetector is a hybrid processor that detects and removes personally identifiable information such as emails, phone numbers, and credit cards. It can redact either user input or model output, depending on where it's applied. It uses an LLM to identify sensitive content based on configured detection types.

src/mastra/agents/private-agent.ts

import { PIIDetector } from "@mastra/core/processors";

export const privateAgent = new Agent({
  id: "private-agent",
  name: "Private Agent",
  inputProcessors: [
    new PIIDetector({
      model: "openrouter/openai/gpt-oss-safeguard-20b",
      threshold: 0.6,
      strategy: "redact",
      redactionMethod: "mask",
      detectionTypes: ["email", "phone", "credit-card"],
      instructions: "Detect and mask personally identifiable information.",
    }),
  ],
  outputProcessors: [
    new PIIDetector(),
  ],
});

info

访问 PIIDetector 查看完整的配置选项列表。

🌐 Visit PIIDetector for a full list of configuration options.

使用多个处理器

🌐 Applying multiple processors

你可以通过在 inputProcessors 或 outputProcessors 数组中列出多个处理器来应用它们。它们按顺序运行，每个处理器接收前一个处理器的输出。

🌐 You can apply multiple processors by listing them in the inputProcessors or outputProcessors array. They run in sequence, with each processor receiving the output of the one before it.

一个典型的订单可能是：

🌐 A typical order might be:

1. 归一化：标准化输入格式（UnicodeNormalizer）。
2. 安全检查：检测威胁或敏感内容（PromptInjectionDetector、PIIDetector）。
3. 过滤：阻止或转换消息 (ModerationProcessor)。

顺序会影响行为，因此请根据你的目标安排处理器。

🌐 The order affects behavior, so arrange processors to suit your goals.

src/mastra/agents/test-agent.ts

import {
  UnicodeNormalizer,
  ModerationProcessor,
  PromptInjectionDetector,
  PIIDetector,
} from "@mastra/core/processors";

export const testAgent = new Agent({
  id: "test-agent",
  name: "Test Agent",
  inputProcessors: [
    new UnicodeNormalizer(),
    new PromptInjectionDetector(),
    new PIIDetector(),
    new ModerationProcessor(),
  ],
});

处理器策略

🌐 Processor strategies

许多内置处理器支持一个 strategy 参数，用于控制它们如何处理标记的输入或输出。支持的值可能包括：block、warn、detect 或 redact。

🌐 Many of the built-in processors support a strategy parameter that controls how they handle flagged input or output. Supported values may include: block, warn, detect, or redact.

大多数策略允许请求不受中断地继续。当使用 block 时，处理器会调用其内部的 abort() 函数，该函数会立即停止请求，并阻止任何后续处理器的运行。

🌐 Most strategies allow the request to continue without interruption. When block is used, the processor calls its internal abort() function, which immediately stops the request and prevents any subsequent processors from running.

src/mastra/agents/private-agent.ts

import { PIIDetector } from "@mastra/core/processors";

export const privateAgent = new Agent({
  id: "private-agent",
  name: "Private Agent",
  inputProcessors: [
    new PIIDetector({
      strategy: "block",
    }),
  ],
});

处理被阻止的请求

🌐 Handling blocked requests

当处理器阻止请求时，代理仍然会成功返回而不会抛出错误。要处理被阻止的请求，请在响应中检查 tripwire。

🌐 When a processor blocks a request, the agent will still return successfully without throwing an error. To handle blocked requests, check for tripwire in the response.

例如，如果代理使用 PIIDetector 与 strategy: "block" 并且请求中包含信用卡号码，它将被阻止，响应将包含警示信息。

🌐 For example, if an agent uses the PIIDetector with strategy: "block" and the request includes a credit card number, it will be blocked and the response will include tripwire information.

.generate() 示例

🌐 .generate() example

const result = await agent.generate(
  "Is this credit card number valid?: 4543 1374 5089 4332",
);

if (result.tripwire) {
  console.error("Blocked:", result.tripwire.reason);
  console.error("Processor:", result.tripwire.processorId);
  // Optional: check if retry was requested
  console.error("Retry requested:", result.tripwire.retry);
  // Optional: access additional metadata
  console.error("Metadata:", result.tripwire.metadata);
}

.stream() 示例

🌐 .stream() example

const stream = await agent.stream(
  "Is this credit card number valid?: 4543 1374 5089 4332",
);

for await (const chunk of stream.fullStream) {
  if (chunk.type === "tripwire") {
    console.error("Blocked:", chunk.payload.reason);
    console.error("Processor:", chunk.payload.processorId);
  }
}

在这种情况下，reason 表示检测到信用卡号码：

🌐 In this case, the reason indicates that a credit card number was detected:

PII detected. Types: credit-card

请求重试

🌐 Requesting retries

处理器可以请求大型语言模型根据反馈重试其响应。这对于执行质量检查非常有用：

🌐 Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks:

export class QualityChecker implements Processor {
  id = "quality-checker";

  async processOutputStep({ text, abort, retryCount }) {
    const score = await evaluateQuality(text);

    if (score < 0.7 && retryCount < 3) {
      // Request retry with feedback for the LLM
      abort("Response quality too low. Please be more specific.", {
        retry: true,
        metadata: { score },
      });
    }

    return [];
  }
}

abort() 函数接受一个可选的第二个参数，包含：

🌐 The abort() function accepts an optional second parameter with:

• retry: true - 请求 LLM 重试该步骤
• metadata: unknown - 附加调试/日志记录数据

使用 retryCount 来跟踪重试次数并防止无限循环。

🌐 Use retryCount to track retry attempts and prevent infinite loops.

自定义处理器

🌐 Custom processors

如果内置处理器无法满足你的需求，你可以通过扩展 Processor 类来创建自己的处理器。

🌐 If the built-in processors don’t cover your needs, you can create your own by extending the Processor class.

可用示例：

🌐 Available examples:

• 消息长度限制器
• 响应长度限制器
• 响应验证器