> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# TokenLimiterProcessor

Le `TokenLimiterProcessor` limite le nombre de tokens dans les messages. Il peut être utilisé comme Processor d'entrée, d'entrée par étape et de sortie :

- **Processor d'entrée** (`processInput`) : filtre les messages historiques afin qu'ils tiennent dans la fenêtre de contexte avant le démarrage de la boucle agentique, en donnant la priorité aux messages récents
- **Processor d'entrée par étape** (`processInputStep`) : élague les messages à chaque étape d'un workflow d'agent en plusieurs étapes, ce qui empêche une croissance illimitée du nombre de tokens lorsque des tools déclenchent des appels supplémentaires au LLM
- **Processor de sortie** : limite les tokens de la réponse générée, en streaming ou non, au moyen de stratégies configurables pour gérer le dépassement des limites

## Exemple d'utilisation

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

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

## Paramètres du constructeur

**options** (`number | Options`): Un simple nombre définissant la limite de tokens, ou un objet d'options de configuration

**options.limit** (`number`): Nombre maximal de tokens autorisé dans la réponse

**options.encoding** (`TiktokenBPE`): Encodage facultatif à utiliser. La valeur par défaut est o200k\_base, employée par gpt-5.1

**options.strategy** (`'truncate' | 'abort'`): Stratégie appliquée lorsque la limite de tokens est atteinte : 'truncate' arrête l'émission de chunks, tandis que 'abort' appelle abort() pour arrêter le flux

**options.countMode** (`'cumulative' | 'part'`): Indique s'il faut compter les tokens depuis le début du flux ou seulement ceux de la partie actuelle : 'cumulative' compte tous les tokens depuis le début, tandis que 'part' ne compte que ceux de la partie actuelle

**options.trimMode** (`'best-fit' | 'contiguous'`): Contrôle la manière dont les messages sont réduits lorsque la limite de tokens est dépassée : 'best-fit' conserve autant de messages que possible (ce qui peut créer des lacunes), tandis que 'contiguous' s'arrête au premier message qui ne tient pas, garantissant ainsi un suffixe continu de l'historique de conversation

## Valeur renvoyée

**id** (`string`): Identifiant du Processor défini sur 'token-limiter'

**name** (`string`): Nom d'affichage facultatif du Processor

**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Filtre les messages d'entrée pour respecter la limite de tokens avant le démarrage de la boucle agentique, en donnant la priorité aux messages récents tout en conservant les messages système

**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Élague les messages à chaque étape de la boucle agentique (y compris lors de la poursuite des appels de tools) afin que la conversation respecte la limite de tokens. Modifie directement messageList en supprimant d'abord les messages les plus anciens tout en conservant les messages système.

**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null>`): Traite les parties de sortie en streaming afin de limiter le nombre de tokens pendant le streaming. Seules les parties texte et objet sont comptabilisées dans la limite et peuvent être retenues ; les parties de cycle de vie, de raisonnement et de tool sont toujours transmises.

**processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Traite les résultats de sortie finaux afin de limiter le nombre de tokens dans les scénarios sans streaming

**getMaxTokens** (`() => number`): Obtient la limite maximale de tokens

## Comportement du flux de sortie

En tant que Processor de sortie, seules les parties qui transportent une sortie générée sont prises en compte dans la limite : `text-delta` et `object`. Les parties du cycle de vie (telles que `step-start`), les deltas de raisonnement, les métadonnées de réponse et les parties de tool (`tool-call`, `tool-result`) ne sont ni comptabilisées ni retenues. Les appels de tools atteignent donc toujours la boucle agentique et sont exécutés.

Avec la stratégie `truncate` par défaut, la première fois qu'une sortie est retenue, le Processor émet une partie transitoire `data-token-limit-reached` dans le flux :

```typescript
for await (const part of stream.fullStream) {
  if (part.type === 'data-token-limit-reached') {
    console.log('output truncated at', part.data.limit, 'tokens')
  }
}
```

## Comportement en cas d'erreur

Lorsqu'il est utilisé comme Processor d'entrée (avec `processInput` comme avec `processInputStep`), `TokenLimiterProcessor` lève une erreur `TripWire` dans les cas suivants :

- **Messages vides** : s'il n'y a aucun message à traiter, un TripWire est levé, car il est impossible d'envoyer une requête à un LLM sans message.
- **Les messages système dépassent la limite** : si les messages système dépassent à eux seuls la limite de tokens, un TripWire est levé, car il est impossible d'envoyer une requête à un LLM contenant uniquement des messages système et aucun message utilisateur ou assistant.

```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)
  }
}
```

## Exemple d'utilisation avancée

### Comme Processor d'entrée (limiter la fenêtre de contexte)

Utilisez `inputProcessors` pour limiter les messages historiques envoyés au modèle et ainsi respecter les limites de la fenêtre de contexte :

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

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

### Comme Processor d'entrée par étape (limiter la croissance des tokens sur plusieurs étapes)

Lorsqu'un agent utilise des tools sur plusieurs étapes (par exemple, avec `maxSteps > 1`), chaque étape accumule l'historique de conversation de toutes les étapes précédentes. Utilisez `inputProcessors` pour limiter également les tokens à chaque étape de la boucle agentique. Le `TokenLimiterProcessor` s'applique automatiquement à l'entrée initiale et à chaque étape suivante :

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

export const agent = new Agent({
  id: 'multi-step-agent',
  name: 'multi-step-agent',
  instructions: 'You are a helpful research assistant with access to tools',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [
    new TokenLimiterProcessor({ limit: 8000 }), // Applied at every step
  ],
})

// Each tool call step will be limited to ~8000 input tokens
const result = await agent.generate('Research this topic using your tools', {
  maxSteps: 10,
})
```

### Comme Processor de sortie (limiter la longueur de la réponse)

Utilisez `outputProcessors` pour limiter la longueur des réponses générées :

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

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

## Ressources associées

- [Garde-fous](https://mastra.zisheng.pro/fr/docs/agents/guardrails)