ToolCallFilter

ToolCallFilter 是一个输入 Processor，会在消息历史记录发送给模型之前，从中滤除 Tool 调用及其结果。当你想从上下文中排除特定 Tool 交互，或彻底移除所有 Tool 调用时，此功能非常有用。

使用示例

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 调用

filterAfterToolSteps?:

number

在 Agent 循环期间启用过滤，并保留最近指定数量的、产生 Tool 调用的步骤中的 Tool 调用和结果。如果为 undefined，则禁用步骤过滤

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 调用和结果。

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

保留精简的模型输出

设置 preserveModelOutput: true，可为过滤器移除的已完成 Tool 结果保留精简的 toModelOutput 历史记录。这样既能将模型侧输出作为文本保留在提示词中，又能移除原始 toolInvocation.args 和 toolInvocation.result 载荷。

只有带有 providerMetadata.mastra.modelOutput 的已完成 Tool 结果才会被保留。Tool 调用、未完成的结果以及没有存储模型输出的结果仍会被过滤。

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

将 preserveModelOutput 与 exclude 结合使用，可以只为被过滤的 Tool 保留精简输出：

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

扩展使用示例

src/mastra/agents/filtered-agent.ts

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 调用

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