TokenLimiter프로세서

그만큼TokenLimiterProcessor메시지의 토큰 수를 제한합니다. 입력, 단계별 입력 및 출력 프로세서로 사용할 수 있습니다.

• 입력 프로세서 (processInput): Agent 루프가 시작되기 전에 최근 메시지를 우선하면서 컨텍스트 창에 맞도록 이전 메시지를 필터링합니다
• 단계별 입력 프로세서 (processInputStep): 여러 단계로 구성된 Agent Workflow의 각 단계에서 메시지를 정리하여 Tool이 추가 LLM 호출을 트리거할 때 토큰이 무제한으로 증가하는 것을 방지합니다
• 출력 프로세서: 구성 가능한 전략을 사용하여 스트리밍 또는 비스트리밍으로 생성된 응답 토큰을 제한하고 한도 초과를 처리합니다.

사용예

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

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

생성자 매개변수

options:

number | Options

토큰 한도를 나타내는 단순 숫자 또는 구성 옵션 객체입니다

number | Options

limit:

number

응답에서 허용할 최대 토큰 수입니다

encoding?:

TiktokenBPE

사용할 선택적 인코딩입니다. 기본값은 gpt-5.1에서 사용하는 o200k_base입니다

strategy?:

'truncate' | 'abort'

토큰 한도에 도달했을 때 사용할 전략입니다. 'truncate'는 청크 방출을 중단하고, 'abort'는 abort()를 호출하여 스트림을 중단합니다

countMode?:

'cumulative' | 'part'

스트림 시작부터 토큰을 계산할지 현재 부분의 토큰만 계산할지 지정합니다. 'cumulative'은 시작부터 모든 토큰을 계산하고, 'part'는 현재 부분의 토큰만 계산합니다

trimMode?:

'best-fit' | 'contiguous'

토큰 한도를 초과할 때 메시지를 정리하는 방식을 제어합니다. 'best-fit'은 가능한 한 많은 메시지를 유지하며(중간에 누락 구간이 생길 수 있음), 'contiguous'는 한도에 맞지 않는 첫 번째 메시지에서 중단하여 대화 기록의 연속된 마지막 구간을 보장합니다

보고

id:

string

'token-limiter'로 설정된 프로세서 식별자입니다

name?:

string

선택적 프로세서 표시 이름입니다

processInput:

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

Agent 루프가 시작되기 전에 시스템 메시지를 보존하면서 최근 메시지를 우선하여 입력 메시지가 토큰 한도에 맞도록 필터링합니다

processInputStep:

(args: ProcessInputStepArgs) => Promise<void>

대화를 토큰 한도 내로 유지하기 위해 Agent 루프의 각 단계(Tool 호출 후속 처리 포함)에서 메시지를 정리합니다. 시스템 메시지를 보존하면서 가장 오래된 메시지부터 제거하여 messageList를 직접 변경합니다.

processOutputStream:

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

스트리밍 중 토큰 수를 제한하기 위해 스트리밍 출력 부분을 처리합니다. 텍스트와 객체 부분만 한도에 포함되어 보류될 수 있으며, 수명 주기, 추론 및 Tool 부분은 항상 그대로 전달됩니다.

processOutputResult:

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

비스트리밍 시나리오에서 토큰 수를 제한하기 위해 최종 출력 결과를 처리합니다

getMaxTokens:

() => number

최대 토큰 한도를 가져옵니다

출력 스트림 동작

출력 프로세서로 사용할 때는 생성된 출력을 전달하는 text-delta 및 object 부분만 한도에 포함됩니다. 수명 주기 부분(예: step-start), 추론 델타, 응답 메타데이터, Tool 부분(tool-call, tool-result)은 계산되거나 보류되지 않으므로 Tool 호출은 항상 Agent 루프에 도달하여 실행됩니다. 기본 truncate 전략에서는 출력이 처음 보류될 때 프로세서가 스트림에 일시적인 data-token-limit-reached 부분을 방출합니다.

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

오류 동작

입력 프로세서로 사용할 경우(processInput 및 processInputStep 모두) TokenLimiterProcessor는 다음 상황에서 TripWire 오류를 발생시킵니다.

• 빈 메시지: 처리할 메시지가 없으면 메시지 없이 LLM 요청을 보낼 수 없기 때문에 TripWire가 발생합니다.
• 시스템 메시지가 한도를 초과했습니다.: 시스템 메시지만 토큰 제한을 초과하는 경우 시스템 메시지만 있고 사용자/보조 메시지 없이 LLM 요청을 보낼 수 없기 때문에 TripWire가 발생합니다.

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

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

확장된 사용 예

입력 프로세서로(컨텍스트 창 제한)

inputProcessors를 사용하여 Model에 전송되는 이전 메시지를 제한하면 컨텍스트 창 한도 내에서 유지하는 데 도움이 됩니다.

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

단계별 입력 프로세서로서(다단계 토큰 증가 제한)

Agent가 여러 단계에 걸쳐 Tool을 사용하는 경우(예: maxSteps > 1) 각 단계에는 이전 모든 단계의 대화 기록이 누적됩니다. inputProcessors를 사용하여 Agent 루프의 각 단계에서도 토큰을 제한하세요. 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,
})

출력 프로세서로 사용(응답 길이 제한)

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

관련된

• 난간