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

# ToolCallFilter

`ToolCallFilter` 是一个**输入 Processor**，会在消息历史记录发送给模型之前，从中滤除 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 的精简模型侧输出。原始 Tool 参数和原始结果会被移除

## 返回值

**id** (`string`): 设为 'tool-call-filter' 的 Processor 标识符

**name** (`string`): 设为 'ToolCallFilter' 的 Processor 显示名称

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

## 相关内容

- [Guardrails](https://mastra.zisheng.pro/docs/agents/guardrails)