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

# ToolCallFilter

`ToolCallFilter` 是一種**輸入處理器**，會在訊息歷史記錄傳送至模型前，篩除 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`): 透過 providerMetadata.mastra.modelOutput，保留已完成且被篩除的 Tool 結果中，精簡、供模型使用的輸出。原始 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 文字會留在情境中。

設定 `filterAfterToolSteps: 0`，可在每個步驟篩除先前所有 Tool 呼叫與結果。

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

## 保留精簡的模型輸出

設定 `preserveModelOutput: true`，可為篩選器移除的已完成 Tool 結果保留精簡的 `toModelOutput` 歷史記錄。這會在提示詞中以文字形式保留供模型使用的輸出，同時移除原始 `toolInvocation.args` 與 `toolInvocation.result` 承載資料。

只有含有 `providerMetadata.mastra.modelOutput` 的已完成 Tool 結果會被保留。Tool 呼叫、未完成的結果，以及未儲存模型輸出的結果仍會被篩除。

```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/zh-TW/docs/agents/guardrails)