TokenLimiterProcessor

TokenLimiterProcessor 會限制訊息的 token 數量。它可用作輸入、每步輸入及輸出 Processor：

• 輸入 Processor（processInput）：在 agentic loop 開始前篩選歷史訊息，使其符合 context window 限制，並優先保留較近期的訊息
• 每步輸入 Processor（processInputStep）：在多步 Agent Workflow 的每一步修剪訊息，避免 Tool 觸發額外 LLM 呼叫時 token 數量無限增長
• 輸出 Processor：透過串流或非串流方式限制所產生回應的 token 數量，並提供可設定的策略來處理超出限制的情況

使用範例

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

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

建構函數參數

options:

number | Options

可以是代表 token 限制的簡單數值，亦可以是設定選項物件

number | Options

limit:

number

回應所允許的 token 數量上限

encoding?:

TiktokenBPE

可選用的編碼。預設為 gpt-5.1 所使用的 o200k_base

strategy?:

'truncate' | 'abort'

達到 token 限制時採用的策略：'truncate' 會停止發出 chunk，'abort' 會呼叫 abort() 以停止串流

countMode?:

'cumulative' | 'part'

決定從串流開始計算 token，還是只計算目前 part：'cumulative' 會計算從開始起的所有 token，'part' 則只計算目前 part 中的 token

trimMode?:

'best-fit' | 'contiguous'

控制超出 token 限制時修剪訊息的方式：'best-fit' 會盡量保留最多訊息（可能產生間斷），'contiguous' 會在遇到第一則無法容納的訊息時停止，確保對話記錄保留連續的末段

傳回值

id:

string

設為 'token-limiter' 的 Processor 識別碼

name?:

string

可選的 Processor 顯示名稱

processInput:

(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>

在 agentic loop 開始前篩選輸入訊息，使其符合 token 限制；優先保留較近期訊息，同時保留系統訊息

processInputStep:

(args: ProcessInputStepArgs) => Promise<void>

在 agentic loop 的每一步（包括 Tool 呼叫的延續步驟）修剪訊息，令對話維持在 token 限制內。它會直接修改 messageList，先移除最舊的訊息，同時保留系統訊息。

processOutputStream:

(args: ProcessOutputStreamArgs) => Promise<ChunkType | null>

處理串流輸出 part，以限制串流期間的 token 數量。只有文字和物件 part 會計入限制並可被扣起；生命週期、推理及 Tool part 一律會通過。

processOutputResult:

(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>

處理最終輸出結果，以限制非串流情況下的 token 數量

getMaxTokens:

() => number

取得 token 數量上限

輸出串流行為

用作輸出 Processor 時，只有承載所產生輸出的 part 才會計入限制：text-delta 和 object。生命週期 part（例如 step-start）、推理 delta、回應中繼資料及 Tool part（tool-call、tool-result）既不會計算，亦不會被扣起，因此 Tool 呼叫總能傳到 agentic loop 並獲執行。

使用預設的 truncate 策略時，Processor 首次扣起輸出，便會在串流中發出暫時性的 data-token-limit-reached part：

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

錯誤行為

用作輸入 Processor（包括 processInput 和 processInputStep）時，TokenLimiterProcessor 會在以下情況拋出 TripWire 錯誤：

• 訊息為空：如果沒有任何訊息可供處理，便會拋出 TripWire，因為你無法在沒有訊息的情況下傳送 LLM 請求。
• 系統訊息超出限制：如果單是系統訊息已超出 token 限制，便會拋出 TripWire，因為你無法傳送只有系統訊息、而沒有使用者／助理訊息的 LLM 請求。

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

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

進階使用範例

用作輸入 Processor（限制 context window）

使用 inputProcessors 限制傳送到模型的歷史訊息，有助保持在 context window 限制內：

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
  ],
})

用作每步輸入 Processor（限制多步驟的 token 增長）

當 Agent 在多個步驟中使用 Tool（例如 maxSteps > 1）時，每一步都會累積之前所有步驟的對話記錄。使用 inputProcessors，亦可限制 agentic loop 每一步的 token 數量。TokenLimiterProcessor 會自動套用於初始輸入及其後每一步：

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

用作輸出 Processor（限制回應長度）

使用 outputProcessors 限制所產生回應的長度：

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',
    }),
  ],
})

相關內容

• 防護機制