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

# TokenLimiter프로세서

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

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

## 사용예

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

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

## 생성자 매개변수

**options** (`number | Options`): 토큰 한도를 나타내는 단순 숫자 또는 구성 옵션 객체입니다

**options.limit** (`number`): 응답에서 허용할 최대 토큰 수입니다

**options.encoding** (`TiktokenBPE`): 사용할 선택적 인코딩입니다. 기본값은 gpt-5.1에서 사용하는 o200k\_base입니다

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

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

**options.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` 부분을 방출합니다.

```typescript
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가 발생합니다.

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

## 확장된 사용 예

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

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

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

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

Agent가 여러 단계에 걸쳐 Tool을 사용하는 경우(예: `maxSteps > 1`) 각 단계에는 이전 모든 단계의 대화 기록이 누적됩니다. `inputProcessors`를 사용하여 Agent 루프의 각 단계에서도 토큰을 제한하세요. `TokenLimiterProcessor`는 초기 입력과 이후 모든 단계에 자동으로 적용됩니다.

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

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

`outputProcessors`를 사용하여 생성되는 응답의 길이를 제한하세요.

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

## 관련된

- [난간](https://mastra.zisheng.pro/ko/docs/agents/guardrails)