# TokenLimiterProcessor

The `TokenLimiterProcessor` limits the number of tokens in messages. It can be used as both an input and output processor:

- **Input processor**: Filters historical messages to fit within the context window, prioritizing recent messages
- **Output processor**: Limits generated response tokens via streaming or non-streaming with configurable strategies for handling exceeded limits

## Usage example

```typescript
import { TokenLimiterProcessor } from '@mastra/core/processors'

const processor = new TokenLimiterProcessor({
  limit: 1000,
  strategy: 'truncate',
  countMode: 'cumulative',
})
```

## Constructor parameters

**options:** (`number | Options`): Either a simple number for token limit, or configuration options object

### Options

**limit:** (`number`): Maximum number of tokens to allow in the response

**encoding?:** (`TiktokenBPE`): Optional encoding to use. Defaults to o200k\_base which is used by gpt-5.1

**strategy?:** (`'truncate' | 'abort'`): Strategy when token limit is reached: 'truncate' stops emitting chunks, 'abort' calls abort() to stop the stream

**countMode?:** (`'cumulative' | 'part'`): Whether to count tokens from the beginning of the stream or just the current part: 'cumulative' counts all tokens from start, 'part' only counts tokens in current part

## Returns

**id:** (`string`): Processor identifier set to 'token-limiter'

**name?:** (`string`): Optional processor display name

**processInput:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Filters input messages to fit within token limit, prioritizing recent messages while preserving system messages

**processOutputStream:** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming

**processOutputResult:** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to limit token count in non-streaming scenarios

**getMaxTokens:** (`() => number`): Get the maximum token limit

## Error behavior

When used as an input processor, `TokenLimiterProcessor` throws a `TripWire` error in the following cases:

- **Empty messages**: If there are no messages to process, a TripWire is thrown because you cannot send an LLM request with no messages.
- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you cannot send an LLM request with only system messages and no user/assistant messages.

```typescript
import { TripWire } from '@mastra/core/agent'

try {
  await agent.generate('Hello')
} catch (error) {
  if (error instanceof TripWire) {
    console.log('Token limit error:', error.message)
  }
}
```

## Extended usage example

### As an input processor (limit context window)

Use `inputProcessors` to limit historical messages sent to the model, which helps stay within context window limits:

```typescript
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { TokenLimiterProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  name: 'context-limited-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-4o',
  memory: new Memory({
    /* ... */
  }),
  inputProcessors: [
    new TokenLimiterProcessor({ limit: 4000 }), // Limits historical messages to ~4000 tokens
  ],
})
```

### As an output processor (limit response length)

Use `outputProcessors` to limit the length of generated responses:

```typescript
import { Agent } from '@mastra/core/agent'
import { TokenLimiterProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  name: 'response-limited-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-4o',
  outputProcessors: [
    new TokenLimiterProcessor({
      limit: 1000,
      strategy: 'truncate',
      countMode: 'cumulative',
    }),
  ],
})
```

## Related

- [Guardrails](https://mastra.ai/docs/agents/guardrails)