ToolCallFilter

ToolCallFilter 是一個輸入 processor，會在將訊息歷史記錄傳送給模型前，篩走 Tool 呼叫及其結果。當你想從 context 中排除特定 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,
})

Constructor 參數

options?:

Options

Tool 呼叫篩選器的設定選項

Options

exclude?:

string[]

要排除的特定 Tool 名稱清單。如未提供或為 undefined，則會排除所有 Tool 呼叫

filterAfterToolSteps?:

number

在 Agent 循環期間啟用篩選，並保留最近指定數量、產生 Tool 呼叫的步驟中的 Tool 呼叫及結果。如為 undefined，則停用步驟篩選

preserveModelOutput?:

boolean

透過 providerMetadata.mastra.modelOutput，保留已完成且被篩選的 Tool 結果中面向模型的精簡輸出。原始 Tool args 及原始結果會被移除

傳回值

id:

string

Processor 標識符，設為 'tool-call-filter'

name:

string

Processor 顯示名稱，設為 '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 文字會保留在 context 中。

設定 filterAfterToolSteps: 0，可在每個步驟篩走所有先前的 Tool 呼叫及結果。

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

保留精簡模型輸出

設定 preserveModelOutput: true，可為篩選器移除的已完成 Tool 結果保留精簡的 toModelOutput 歷史記錄。這會將面向模型的輸出以文字形式保留在 prompt 中，同時移除原始 toolInvocation.args 及 toolInvocation.result payload。

只有包含 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