ToolCallFilter

그만큼ToolCallFilter은입력 프로세서Model로 보내기 전에 메시지 기록에서 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이 있는 결과에서 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을 설정하세요.

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

컴팩트 Model 출력 유지

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

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

관련된

• 난간