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

# ToolCallFilter

그만큼`ToolCallFilter`은**입력 프로세서**Model로 보내기 전에 메시지 기록에서 Tool 호출과 그 결과를 필터링합니다. 이는 특정 Tool 상호 작용을 컨텍스트에서 제외하거나 모든 Tool 호출을 완전히 제거하려는 경우에 유용합니다.

## 사용예

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

// Exclude all tool calls
const filterAll = new ToolCallFilter()

// Exclude specific tools by name
const filterSpecific = new ToolCallFilter({
  exclude: ['searchDatabase', 'sendEmail'],
})

// Enable filtering during agent loops and keep the two most recent tool-producing steps
const filterAfterRecentTools = new ToolCallFilter({
  filterAfterToolSteps: 2,
})

// Preserve compact model-facing output for filtered completed tool results
const filterWithCompactToolHistory = new ToolCallFilter({
  preserveModelOutput: true,
})
```

## 생성자 매개변수

**options** (`Options`): Tool 호출 필터의 구성 옵션입니다

**options.exclude** (`string[]`): 제외할 특정 Tool 이름 목록입니다. 제공하지 않거나 undefined이면 모든 Tool 호출이 제외됩니다

**options.filterAfterToolSteps** (`number`): Agent 루프 중 필터링을 활성화하고, 이 수만큼의 최근 Tool 생성 단계에 포함된 Tool 호출과 결과를 보존합니다. undefined이면 단계 필터링이 비활성화됩니다

**options.preserveModelOutput** (`boolean`): 필터링된 완료 Tool 결과 중 providerMetadata.mastra.modelOutput이 있는 결과에서 Model에 전달되는 간결한 출력을 보존합니다. 원시 Tool 인수와 원시 결과는 제거됩니다

## 보고

**id** (`string`): 'tool-call-filter'로 설정된 프로세서 식별자입니다

**name** (`string`): 'ToolCallFilter'로 설정된 프로세서 표시 이름입니다

**processInput** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): 구성에 따라 Tool 호출과 해당 결과를 걸러내도록 입력 메시지를 처리합니다

**processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): filterAfterToolSteps가 구성된 경우 Agent 루프 단계의 입력을 처리합니다. 단계 필터링이 비활성화되어 있으면 변경 사항을 반환하지 않습니다

## 단계 필터링

기본적으로 `ToolCallFilter`는 Agent 루프가 시작되기 전 초기 입력만 필터링합니다. 각 루프 단계에서도 필터링하려면 `filterAfterToolSteps`를 설정하세요. `filterAfterToolSteps`는 Tool을 생성한 단계의 수를 계산합니다. 예를 들어 `filterAfterToolSteps: 2`는 가장 최근의 Tool 생성 단계 두 개에서 발생한 Tool 호출과 결과를 유지하고, 그보다 오래된 Tool 호출과 결과는 필터링합니다. Tool과 관련 없는 텍스트는 컨텍스트에 유지됩니다. 각 단계에서 이전의 모든 Tool 호출과 결과를 필터링하려면 `filterAfterToolSteps: 0`을 설정하세요.

```typescript
const filter = new ToolCallFilter({
  filterAfterToolSteps: 2,
})
```

## 컴팩트 Model 출력 유지

필터가 제거하는 완료된 Tool 결과의 간결한 `toModelOutput` 기록을 유지하려면 `preserveModelOutput: true`를 설정하세요. 이렇게 하면 원시 `toolInvocation.args` 및 `toolInvocation.result` 페이로드를 제거하면서 Model에 전달되는 출력을 Prompt에 텍스트로 유지합니다. `providerMetadata.mastra.modelOutput`이 있는 완료된 Tool 결과만 보존됩니다. Tool 호출, 완료되지 않은 결과, 저장된 Model 출력이 없는 결과는 계속 필터링됩니다.

```typescript
const filter = new ToolCallFilter({
  preserveModelOutput: true,
})
```

`preserveModelOutput`과 `exclude`를 함께 사용하여 필터링된 Tool에 대해서만 간결한 출력을 보존하세요.

```typescript
const filter = new ToolCallFilter({
  exclude: ['searchDatabase'],
  preserveModelOutput: true,
})
```

## 확장된 사용 예

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

export const agent = new Agent({
  id: 'filtered-agent',
  name: 'filtered-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  tools: {
    searchDatabase,
    sendEmail,
    getWeather,
  },
  inputProcessors: [
    // Filter out database search tool calls from context
    // to reduce token usage while keeping other tool interactions
    new ToolCallFilter({
      exclude: ['searchDatabase'],
    }),
  ],
})
```

## 모든 Tool 호출 필터링

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

export const agent = new Agent({
  id: 'no-tools-context-agent',
  name: 'no-tools-context-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
  tools: {
    searchDatabase,
    sendEmail,
  },
  inputProcessors: [
    // Remove all tool calls from the message history
    // The agent can still use tools, but previous tool interactions
    // won't be included in the context
    new ToolCallFilter(),
  ],
})
```

## 관련된

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