Introducing Token Limiting for Mastra Agents

You can now cap token usage with TokenLimiterProcessor — a processor that enforces a limit on inputs and generated responses. Configure it as an inputProcessor to trim message history when it exceeds the cap, or as an outputProcessor to abort or truncate the response mid-stream.

Strategies range from a silent truncate to a hard abort. Additional configuration lets you pick between best-fit and contiguous trimming for inputs, and whole-response or per-stream-part for outputs.

Without a token limiter, a growing message history can bloat the model's context window and get rejected mid-turn. Similarly, a long response can exceed the length expected by a UI or downstream service. With TokenLimiterProcessor you can catch both — trim the history before it hits the LLM, or stop the response the moment it crosses the threshold.

Studio surfaces the abort tripwire as a "Content Blocked" panel during development, letting you inspect the token count. For production, observability traces surface the same details.

Get started

Install @mastra/core along with the observability + storage packages needed to persist tripwire data:

npm install @mastra/core @mastra/observability @mastra/duckdb

Create a TokenLimiterProcessor and attach it to the agent as either an input or output processor. Each option tunes a different dimension of the limit:

• limit: 500: Max tokens on input or output.
• strategy: "abort" (output): Halts with a tripwire. Or "truncate" (silent).
• countMode: "cumulative" Counts across the whole stream, or "part" per chunk.

import { Agent } from "@mastra/core/agent";
import { TokenLimiterProcessor } from "@mastra/core/processors";
 
const outputLimiter = new TokenLimiterProcessor({
  limit: 500,
  strategy: "abort",
  countMode: "cumulative"
});
 
export const researchAgent = new Agent({
  // ...
  outputProcessors: [outputLimiter]
});

To use as an input processor for trimming message history:

• limit: 5000: Trim the message list when it exceeds this cap.
• trimMode: "best-fit": Drop oldest messages first, preserve system messages.

import { Agent } from "@mastra/core/agent";
import { TokenLimiterProcessor } from "@mastra/core/processors";
 
const inputLimiter = new TokenLimiterProcessor({
  limit: 5000,
  trimMode: "best-fit"
});
 
export const researchAgent = new Agent({
  // ...
  inputProcessors: [inputLimiter]
});

To surface tripwires in the traces, configure storage and observability on your main Mastra instance:

import { Mastra } from "@mastra/core/mastra";
import { MastraCompositeStore } from "@mastra/core/storage";
import { DuckDBStore } from "@mastra/duckdb";
import { Observability, MastraStorageExporter } from "@mastra/observability";
 
export const mastra = new Mastra({
  // ...
  storage: new MastraCompositeStore({
    // ...
    domains: {
      observability: await new DuckDBStore().getStore("observability")
    }
  }),
  observability: new Observability({
    configs: {
      default: { exporters: [new MastraStorageExporter()] }
    }
  })
});

For more information and full configuration options, see:

• TokenLimiterProcessor reference
• TokenCostControl reference
• MastraCompositeStore reference
• MastraStorageExporter reference
• Observability overview