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

# 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

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

## 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

**options.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é

**options.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.

```typescript
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.

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

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

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

## Exemple d'utilisation avancée

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

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

## Voir aussi

- [Garde-fous](https://mastra.zisheng.pro/fr/docs/agents/guardrails)