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

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

number | Options

limit:

number

Nombre maximal de tokens autorisé dans la réponse

encoding?:

TiktokenBPE

Encodage facultatif à utiliser. La valeur par défaut est o200k_base, employée par gpt-5.1

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

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

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 :

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.

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 :

src/mastra/agents/context-limited-agent.ts

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 :

src/mastra/agents/multi-step-agent.ts

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 :

src/mastra/agents/response-limited-agent.ts

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