Mastra Processors: la capa de guardrails que se ejecuta en cada paso

TL;DR

• El patrón de frontera — sanear antes, filtrar después — tiene fugas. Los agents fallan en medio del loop: el modelo elige una tool rara, alucina un reembolso, o quema $40 en reintentos.
• Mastra divide los guardrails en inputProcessors (antes del LLM) y outputProcessors (después), y ambos corren en cada paso.
• El loop de reintentos — abort({ retry: true }) + retryCount + maxProcessorRetries — es lo que convierte un guardrail de “bloquear” a “decirle al modelo qué hizo mal y dejar que vuelva a intentar”.
• Un stack real para un agent de cara al cliente tiene cinco processors de entrada y cuatro de salida. A continuación recorro el que yo despliego.
• Este es el segundo post de una serie sobre harness engineering con Mastra. La parte 1 cubre el mapa del harness.

Por qué el patrón de frontera no alcanza

El diseño de guardrails que aparece por defecto en los tutoriales:

1. Validar el input del usuario antes de que llegue al agent.
2. Filtrar la salida final del agent antes de mostrarla al usuario.

Ese es el patrón de frontera. Buen punto de partida, pero lejos de ser suficiente para algo de cara al cliente.

El loop de un agent no es un único input → output. Es razonar → llamar tool → observar → razonar → … → respuesta final. Cada paso de razonamiento puede fallar: el modelo elige la tool equivocada, produce una respuesta intermedia vaga que envenena al siguiente paso, queda en loop sobre la misma llamada, o se compromete a algo que no tiene autoridad para comprometer.

Ninguno de esos errores se ve mal en la frontera. Solo terminan en una respuesta final mala, una factura alta, un cliente enojado, o las tres cosas juntas.

Los processors de Mastra corren adentro del loop — en cada paso, sobre cada salida del modelo, antes y después de cada llamada a una tool.

Los dos pipelines

Los agents de Mastra tienen tres arrays de processors:

1
new Agent({
2
  inputProcessors: [...],   // antes del LLM, en cada paso
3
  outputProcessors: [...],  // después del LLM, en cada paso
4
  errorProcessors: [...],   // cuando el API del proveedor rechaza la llamada
5
});

Los input processors no solo corren sobre el primer mensaje del usuario — corren en cada paso, incluidos los que vienen de regreso desde llamadas a tools. Los output processors corren sobre cada respuesta del modelo antes de que se disparen las tools y antes de que la memoria persista nada.

Ese último detalle importa mucho. Si un output processor aborta, la memoria no guarda la respuesta mala. El historial del agent queda limpio.

El pipeline de entrada

Es donde van las cosas baratas, rápidas y defensivas — todo lo que conviene correr antes de gastar dinero en el modelo principal.

1
import {
2
  CostGuardProcessor,
3
  ModerationProcessor,
4
  PIIDetector,
5
  PromptInjectionDetector,
6
  UnicodeNormalizer,
7
} from '@mastra/core/processors';
8

9
const GUARDRAIL_MODEL = 'groq/openai/gpt-oss-120b';
10

11
export const supportAgent = new Agent({
12
  // ...
13
  inputProcessors: [
14
    new UnicodeNormalizer({
15
      stripControlChars: true,
16
      collapseWhitespace: true,
17
      trim: true,
18
    }),
19
    new PromptInjectionDetector({
20
      model: GUARDRAIL_MODEL,
21
      strategy: 'rewrite',
22
      threshold: 0.8,
23
      detectionTypes: ['injection', 'jailbreak', 'system-override'],
24
      lastMessageOnly: true,
25
    }),
26
    new PIIDetector({
27
      model: GUARDRAIL_MODEL,
28
      strategy: 'redact',
29
      redactionMethod: 'mask',
30
      threshold: 0.6,
31
      detectionTypes: ['email', 'phone', 'credit-card', 'ssn'],
32
      preserveFormat: true,
33
      lastMessageOnly: true,
34
    }),
35
    new ModerationProcessor({
36
      model: GUARDRAIL_MODEL,
37
      strategy: 'block',
38
      threshold: 0.7,
39
      categories: ['hate', 'harassment', 'violence', 'sexual'],
40
      lastMessageOnly: true,
41
    }),
42
    new CostGuardProcessor({
43
      maxCost: 2.0,
44
      scope: 'thread',
45
      window: '24h',
46
    }),
47
  ],
48
});

El orden es deliberado.

UnicodeNormalizer corre primero. Saca zero-width spaces, normaliza formas raras de Unicode y colapsa whitespace. Barato, determinista, y atrapa una cantidad sorprendente de intentos de injection de baja calidad (caracteres invisibles que vienen pegados de prompts copiados de blogs).

PromptInjectionDetector corre segundo. Un clasificador puntúa el mensaje contra patrones de jailbreak. Uso 'rewrite' en lugar de 'block' porque los usuarios legítimos a veces parecen atacantes sin querer (“ignorá la pregunta anterior, y respecto a…”). Reescribir neutraliza el patrón; la conversación sigue.

PIIDetector corre tercero. Emails, teléfonos y tarjetas quedan enmascarados antes de que el modelo principal los vea — tanto por cumplimiento como para que tus prompts no terminen siendo una superficie de PII en los logs del proveedor. lastMessageOnly: true es crítico, o el detector vuelve a escanear todo el historial en cada paso.

ModerationProcessor corre cuarto. Misma forma, distintas categorías. A este lo dejo en block — no tiene sentido reescribir discurso de odio como pregunta.

CostGuardProcessor corre al final. Para cuando llega acá, el mensaje ya está normalizado, neutralizado, redactado y moderado. El cost guard aborta antes de la llamada al modelo principal si el thread alcanzó su tope. scope: 'thread' + window: '24h' = “$2 por conversación por día". Un actor malicioso no puede quemar$200 despotricando contra el agent una hora seguida.

El patrón: lo barato y determinista primero, lo caro y probabilístico al final. UnicodeNormalizer ni siquiera toca la red. La llamada al agent principal solo ocurre si todo lo anterior estuvo de acuerdo.

El pipeline de salida y el loop de reintentos

Los output processors imponen criterio — voz, exactitud, reglas de negocio. Corren sobre cada respuesta del modelo antes de que se disparen las tools, así que pueden pedir un reintento sin que el historial vea la versión mala.

1
import {
2
  BatchPartsProcessor,
3
  PIIDetector,
4
} from '@mastra/core/processors';
5
import { BrandVoiceGuardrail } from '../processors/brand-voice-guardrail';
6
import { UnauthorizedPromiseGuardrail } from '../processors/unauthorized-promise-guardrail';
7

8
outputProcessors: [
9
  new BatchPartsProcessor({ batchSize: 10, maxWaitTime: 150 }),
10
  new PIIDetector({
11
    model: GUARDRAIL_MODEL,
12
    strategy: 'redact',
13
    redactionMethod: 'placeholder',
14
    threshold: 0.6,
15
    detectionTypes: ['email', 'phone', 'credit-card', 'ssn'],
16
  }),
17
  new BrandVoiceGuardrail(),
18
  new UnauthorizedPromiseGuardrail(),
19
],
20
maxProcessorRetries: 3,

BatchPartsProcessor es un truco de performance para streaming, lo retomo más adelante.

PII también corre en la salida — el modelo puede filtrar datos que aprendió en turnos anteriores (el email de un cliente, un ID de orden que no era suyo). Misma clase, distinta config (placeholder lee mejor en respuestas a clientes que mask).

Los dos guardrails custom son donde está la parte interesante.

Guardrail custom #1: voz de marca

Hay dos modos de fallo que aparecen todo el tiempo en agents de cara al cliente:

1. Rechazos vagos. “No puedo ayudarte con eso” cuando justo al lado tiene una búsqueda en la base de conocimiento.
2. Voz de IA. “Como asistente de IA, yo…” — el momento en que un cliente lee eso, se cae la confianza.

El processor que yo uso:

1
import type { Processor } from '@mastra/core/processors';
2

3
const MIN_USEFUL_CHARS = 80;
4

5
const VOICE_VIOLATIONS = [
6
  {
7
    pattern: /\bas an (ai|llm|language model|assistant)\b/i,
8
    feedback:
9
      'Drop the "As an AI..." framing. Speak as a member of the support team — direct and helpful.',
10
  },
11
  {
12
    pattern: /^i (don't|do not|can't|cannot) (know|find|access|browse|see)/i,
13
    feedback:
14
      'Avoid vague refusals. Search the knowledge base, look up the account, or escalate before saying you cannot help.',
15
  },
16
  {
17
    pattern: /\b(unfortunately|sadly),? i('m| am) (unable|not able)/i,
18
    feedback:
19
      'No theatrical apologies. State the constraint, then offer the next step the customer can take.',
20
  },
21
];
22

23
export class BrandVoiceGuardrail implements Processor {
24
  id = 'brand-voice-guardrail';
25

26
  async processOutputStep({
27
    text,
28
    abort,
29
    retryCount,
30
    finishReason,
31
    messageList,
32
  }: Parameters<NonNullable<Processor['processOutputStep']>>[0]) {
33
    if (finishReason === 'tool-calls' || !text) return messageList;
34

35
    const issues: string[] = [];
36

37
    if (text.length < MIN_USEFUL_CHARS) {
38
      issues.push(
39
        'Response is too short to be useful to the customer — expand with concrete steps.',
40
      );
41
    }
42

43
    for (const { pattern, feedback } of VOICE_VIOLATIONS) {
44
      if (pattern.test(text)) issues.push(feedback);
45
    }
46

47
    if (issues.length > 0 && retryCount < 3) {
48
      abort(issues.join(' '), {
49
        retry: true,
50
        metadata: { processor: this.id, issues },
51
      });
52
    }
53

54
    return messageList;
55
  }
56
}

Cuatro decisiones para resaltar.

El early return es clave. Los pasos que solo produjeron una tool call no tienen texto. Si igual les corrés los chequeos de texto, vas a tener falsos positivos que reintentan para siempre.

abort es más que “parar”. Llamado con { retry: true }, el paso se reinicia y el string de reason se inyecta en el contexto del modelo como una corrección. Tratá esos strings como si fueran prompts — porque lo son.

El presupuesto de reintentos tiene dos límites. Uno dentro del processor (retryCount < 3) y otro a nivel agent (maxProcessorRetries: 3). También limito adentro del processor porque depender solo del tope del agent convierte un guardrail roto en un comebolas silencioso dentro de un loop más largo.

Los patrones son regex, no jueces LLM. Los output processors corren en cada paso. Un guardrail lento se acumula. Dejá los chequeos semánticos para los scorers, que corren de manera asíncrona después de que termina la conversación.

Guardrail custom #2: promesas no autorizadas

La voz de marca es criterio. Esto otro es una regla de negocio dura.

Los agents de soporte hablan con clientes sobre dinero — reembolsos, créditos, términos de SLA. Ninguna de esas decisiones le corresponde al LLM. Le corresponden a un humano con autoridad. El trabajo del modelo es triagear y escalar.

1
import type { Processor } from '@mastra/core/processors';
2

3
const COMMITMENT_PATTERNS = [
4
  /\b(refund|credit|reimburse|chargeback)\b/i,
5
  /\b(guarantee[ds]?|promise|commit) (?:that|to|you)\b/i,
6
  /\b(100%|always|never) (?:uptime|available|working)\b/i,
7
  /\bwe will (?:waive|comp|discount|cancel)\b/i,
8
  /\b(SLA|service level agreement)\b/i,
9
];
10

11
export class UnauthorizedPromiseGuardrail implements Processor {
12
  id = 'unauthorized-promise-guardrail';
13

14
  async processOutputStep({
15
    text,
16
    abort,
17
    retryCount,
18
    finishReason,
19
    messageList,
20
  }: Parameters<NonNullable<Processor['processOutputStep']>>[0]) {
21
    if (finishReason === 'tool-calls' || !text) return messageList;
22

23
    const triggered = COMMITMENT_PATTERNS.filter((p) => p.test(text));
24
    if (triggered.length === 0) return messageList;
25

26
    if (retryCount < 2) {
27
      abort(
28
        'You made a commitment the support agent is not authorized to make ' +
29
          '(refund, credit, guarantee, or SLA promise). Do not commit on the company\'s behalf — ' +
30
          'call the escalateToHuman tool with a precise summary so a human agent can approve.',
31
        {
32
          retry: true,
33
          metadata: { processor: this.id, patterns: triggered.map(String) },
34
        },
35
      );
36
    }
37

38
    abort(
39
      'This request needs approval from a human support agent. It has been flagged for escalation.',
40
      { metadata: { processor: this.id, patterns: triggered.map(String) } },
41
    );
42
    return messageList;
43
  }
44
}

Lo importante: el mensaje del reintento no dice solo “no hagás eso”. Le dice al modelo qué hacer en su lugar — llamar a escalateToHuman. Esa tool vive en el toolbelt del agent:

1
export const escalateToHuman = createTool({
2
  id: 'escalate-to-human',
3
  description:
4
    'Escalate the conversation to a human support agent. Use when the customer ' +
5
    'requests a refund, account changes, contract renegotiation, or any commitment ' +
6
    'beyond providing information from the knowledge base.',
7
  inputSchema: z.object({
8
    reason: z.string().min(10),
9
    urgency: z.enum(['low', 'normal', 'high']),
10
    summary: z.string(),
11
  }),
12
  // ...
13
});

El patrón: un processor atrapa al modelo haciendo lo incorrecto y lo redirige a la tool correcta. Después de un reintento, el modelo normalmente entiende. El cliente termina con un ID de ticket (“derivado a nuestro equipo, ticket T-XYZ, respuesta en ~12 min”) en vez de un rechazo genérico.

Si después de dos reintentos el modelo sigue sin escalar, el processor hace un hard abort con un mensaje seguro de cara al público. Ese tercer camino importa — sin él, un modelo con bugs podría quemar todo el presupuesto de reintentos en el mismo error.

Performance: batching y paralelismo

Un stack de cinco guardrails puede duplicar la latencia de cada paso. Cómo mantenerlos rápidos:

Truco 1: lastMessageOnly: true. Sin esto, cada guardrail re-escanea el historial completo en cada paso. Con esto, solo el último mensaje. En conversaciones largas la diferencia es 10x en llamadas al clasificador.

Truco 2: modelos clasificadores más chicos para los guardrails. El agent principal puede ser un modelo de 120B; los clasificadores de los guardrails no tienen por qué. Un clasificador chico hecho a propósito (Llama Prompt-Guard, gpt-oss-safeguard) hace el mismo trabajo ~5x más rápido y barato. En este ejemplo yo corro todo sobre el modelo principal por simplicidad — antes de escalar, conviene meter uno más chico.

Truco 3: BatchPartsProcessor. Los agents en streaming emiten decenas de chunks de text-delta por segundo. Correr un guardrail respaldado por LLM en cada uno es suicidio. BatchPartsProcessor junta chunks y los emite en grupos:

1
outputProcessors: [
2
  new BatchPartsProcessor({ batchSize: 10, maxWaitTime: 150 }),
3
  // todo guardrail abajo de esta línea ve batches de ~10 chunks
4
  new PIIDetector({ model: GUARDRAIL_MODEL, strategy: 'redact' }),
5
],

Siempre va antes de cualquier output processor caro.

Truco 4: processors en paralelo dentro de un workflow. Varios guardrails que solo hacen block (sin mutar) son independientes y pueden correr juntos. Se envuelven en un workflow con .parallel() y se pasa eso como un solo “processor”:

1
import { createWorkflow, createStep } from '@mastra/core/workflows';
2
import { ProcessorStepSchema, PIIDetector, ModerationProcessor } from '@mastra/core/processors';
3

4
const outputGuardrails = createWorkflow({
5
  id: 'output-guardrails',
6
  inputSchema: ProcessorStepSchema,
7
  outputSchema: ProcessorStepSchema,
8
})
9
  .parallel([
10
    createStep(new PIIDetector({ strategy: 'redact' })),
11
    createStep(new ModerationProcessor({ strategy: 'block' })),
12
  ])
13
  .map(async ({ inputData }) => inputData['processor:pii-detector'])
14
  .commit();

El paso .map elige qué rama propaga su salida hacia adelante. Si tenés processors que mutan (redact), mapeás a esa rama.

No conviene meterse con esto hasta tener al menos tres guardrails independientes respaldados por LLM. Por debajo de eso, el overhead del workflow no compensa.

Para qué no sirven los processors

Los processors corren sincrónicamente adentro del loop del agent. Son la herramienta correcta para chequeos semánticos rápidos. Son la incorrecta para:

Evaluación cara basada en LLM. Juzgar la calidad de las citas con un modelo grande va en un scorer (asíncrono, muestreado, no bloquea el loop). Meter una llamada al LLM adentro de processOutputStep duplica latencia y costo en cada paso.

Side effects. No mandés notificaciones, no actualicés bases de datos, no llamés a APIs externas adentro de un processor. Si el paso se reintenta, el processor se vuelve a ejecutar y disparás el side effect dos veces. Los side effects van en el execute de la tool o en hooks post-ejecución. Excepción: los callbacks onViolation, que están explícitamente pensados como fire-and-forget para logging y paginado.

Validación estructural. Los schemas de input de tus tools ya lo hacen. Confiá en la capa de schemas de Mastra; no la reimplementés.

La regla: rápido, semántico, sobre el razonamiento del modelo — es un processor. Lento, caro, o un side effect — no lo es.

El stack de producción completo

Para el agent de soporte, de punta a punta:

1
export const supportAgent = new Agent({
2
  id: 'support-agent',
3
  name: 'Support Agent',
4
  instructions: `...`,
5
  model: 'groq/openai/gpt-oss-120b',
6
  tools: { escalateToHuman },
7
  memory: new Memory({
8
    storage: new LibSQLStore({ id: 'support-storage', url: 'file:./mastra.db' }),
9
    options: { lastMessages: 20 },
10
  }),
11
  inputProcessors: [
12
    new UnicodeNormalizer({ stripControlChars: true, collapseWhitespace: true, trim: true }),
13
    new PromptInjectionDetector({ model: GUARDRAIL_MODEL, strategy: 'rewrite', threshold: 0.8, lastMessageOnly: true }),
14
    new PIIDetector({ model: GUARDRAIL_MODEL, strategy: 'redact', redactionMethod: 'mask', lastMessageOnly: true }),
15
    new ModerationProcessor({ model: GUARDRAIL_MODEL, strategy: 'block', threshold: 0.7, lastMessageOnly: true }),
16
    new CostGuardProcessor({ maxCost: 2.0, scope: 'thread', window: '24h' }),
17
  ],
18
  outputProcessors: [
19
    new BatchPartsProcessor({ batchSize: 10, maxWaitTime: 150 }),
20
    new PIIDetector({ model: GUARDRAIL_MODEL, strategy: 'redact', redactionMethod: 'placeholder' }),
21
    new BrandVoiceGuardrail(),
22
    new UnauthorizedPromiseGuardrail(),
23
  ],
24
  maxProcessorRetries: 3,
25
  defaultOptions: { maxSteps: 10 },
26
});

Cinco input processors, cuatro output processors, un tope de costo, un tope de reintentos. ~30 líneas de config del agent más dos archivos de processors custom. Chico como para entrar en una sola pantalla, completo como para poner enfrente de clientes reales.

El modelo mental: los processors son el sistema inmunológico del harness. Chequeos chicos y rápidos que corren todo el tiempo, con la capacidad de decir “no, intentá de nuevo” antes de que algo malo se propague.

Preguntas frecuentes

Cierre

El patrón de frontera es donde todos empiezan. Los processors son lo que se agrega cuando ya viste a tu agent prometer con seguridad un reembolso que no puede dar, quemar ocho pasos en un loop, o filtrarle a un cliente su propio email — y querés que esos modos de fallo no vuelvan a llegar al usuario.

En el próximo episodio: tools MCP, y por qué el string de descripción de una tool es el string más importante de todo tu harness.

Si estás construyendo algo por acá, me encontrás en X.