ToolCallFilter

ToolCallFilter est un Processor d'entrée qui filtre les appels de Tool et leurs résultats dans l'historique des messages avant son envoi au modèle. Il est utile lorsque vous souhaitez exclure du contexte certaines interactions avec des Tools ou supprimer entièrement tous les appels de Tool.

Exemple d'utilisation

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

Paramètres du constructeur

options?:

Options

Options de configuration du filtre d'appels de Tool

Options

exclude?:

string[]

Liste des noms des Tools précis à exclure. Si elle n'est pas fournie ou vaut undefined, tous les appels de Tool sont exclus

filterAfterToolSteps?:

number

Active le filtrage pendant les boucles de l'Agent et conserve les appels de Tool et les résultats du nombre indiqué d'étapes récentes ayant produit des Tools. Si la valeur est undefined, le filtrage par étape est désactivé

preserveModelOutput?:

boolean

Conserve la sortie compacte destinée au modèle des résultats de Tool terminés et filtrés qui contiennent providerMetadata.mastra.modelOutput. Les arguments bruts des Tools et leurs résultats bruts sont supprimés

Valeur renvoyée

id:

string

Identifiant du Processor défini sur 'tool-call-filter'

name:

string

Nom d'affichage du Processor défini sur 'ToolCallFilter'

processInput:

(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>

Traite les messages d'entrée afin de filtrer les appels de Tool et leurs résultats selon la configuration

processInputStep:

(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>

Traite l'entrée de l'étape de la boucle de l'Agent lorsque filterAfterToolSteps est configuré. Ne renvoie aucune modification lorsque le filtrage par étape est désactivé

Filtrage par étape

Par défaut, ToolCallFilter filtre uniquement l'entrée initiale avant le démarrage de la boucle de l'Agent. Définissez filterAfterToolSteps afin d'appliquer également le filtrage pendant chaque étape de la boucle.

filterAfterToolSteps compte les étapes ayant produit des Tools. Par exemple, filterAfterToolSteps: 2 conserve les appels de Tool et les résultats des deux étapes les plus récentes ayant produit des Tools, et filtre les appels et résultats plus anciens. Le texte qui ne provient pas d'un Tool reste dans le contexte.

Définissez filterAfterToolSteps: 0 pour filtrer tous les appels de Tool et résultats précédents à chaque étape.

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

Conservation de la sortie compacte du modèle

Définissez preserveModelOutput: true pour conserver un historique toModelOutput compact des résultats de Tool terminés supprimés par le filtre. La sortie destinée au modèle est ainsi conservée sous forme de texte dans le prompt, tandis que les charges utiles brutes toolInvocation.args et toolInvocation.result sont supprimées.

Seuls les résultats de Tool terminés qui contiennent providerMetadata.mastra.modelOutput sont conservés. Les appels de Tool, les résultats incomplets et les résultats sans sortie de modèle stockée sont toujours filtrés.

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

Associez preserveModelOutput à exclude pour conserver la sortie compacte uniquement pour les Tools filtrés :

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

Exemple d'utilisation avancée

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

Filtrage de tous les appels de 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(),
  ],
})

Voir aussi

• Garde-fous