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

# CostGuardProcessor

`CostGuardProcessor` applique des limites de coût monétaire à l'ensemble de la boucle agentique et bloque l'exécution ou émet un avertissement lorsqu'un seuil de coût configurable est dépassé.

Il utilise `processInputStep` pour vérifier la limite de coût avant chaque appel au LLM. Pour toutes les portées, les données de coût sont obtenues auprès des API de stockage de l'observabilité (`getMetricAggregate`). Pour les portées `resource` et `thread`, le Processor agrège le coût des différentes exécutions dans une fenêtre temporelle configurable (7 jours par défaut). Pour la portée `run`, il interroge le coût de la Trace actuelle.

Pour appliquer des limites basées sur les tokens, utilisez plutôt `TokenLimiterProcessor`.

Trois modes de portée sont pris en charge :

- **Portée de l'exécution** : suit le coût d'une seule exécution d'Agent au moyen de l'identifiant de Trace
- **Portée de la ressource** (par défaut) : suit le coût cumulé de chaque `resourceId` sur plusieurs exécutions
- **Portée du thread** : suit le coût cumulé de chaque `threadId` sur plusieurs exécutions

> **Garde de coût approximative.** Les données de coût sont conservées de manière asynchrone par des Exporters avec mémoire tampon dans le pipeline d'observabilité. Les Agents qui s'exécutent rapidement peuvent dépasser la limite configurée avant que les métriques ne soient disponibles pour interrogation. Considérez `maxCost` comme un seuil approximatif que ces Agents peuvent dépasser.

## Exemple d'utilisation

Suivez le coût cumulé de chaque ressource (portée par défaut) :

```typescript
import { CostGuardProcessor } from '@mastra/core/processors'

const costGuard = new CostGuardProcessor({
  maxCost: 1.0,
})
```

Suivez le coût cumulé de chaque thread dans une fenêtre de 24 heures :

```typescript
import { CostGuardProcessor } from '@mastra/core/processors'

const costGuard = new CostGuardProcessor({
  maxCost: 5.0,
  scope: 'thread',
  window: '24h',
})
```

Associez le Processor à un Agent avec une fonction de rappel `onViolation` :

```typescript
import { Agent } from '@mastra/core/agent'
import { CostGuardProcessor } from '@mastra/core/processors'

const costGuard = new CostGuardProcessor({
  maxCost: 5.0,
  scope: 'resource',
  window: '30d',
})

costGuard.onViolation = ({ detail }) => {
  console.log(`Cost exceeded for ${detail.scopeKey}: $${detail.usage}/$${detail.limit}`)
}

const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  model: 'openai/gpt-5-nano',
  processors: {
    input: [costGuard],
  },
})
```

## Paramètres du constructeur

**maxCost** (`number`): Coût estimé maximal autorisé (par exemple, 0.50 pour 0,50 USD). Doit être un nombre positif. Utilise les données de coût des métriques d'observabilité. Cette limite est approximative en raison du délai de persistance des métriques.

**scope** (`'run' | 'resource' | 'thread'`): Portée du suivi du coût. 'run' suit le coût de l'exécution actuelle de l'Agent au moyen de l'identifiant de Trace. 'resource' suit le coût cumulé de chaque resourceId sur plusieurs exécutions (par défaut). 'thread' suit le coût cumulé de chaque threadId sur plusieurs exécutions. Toutes les portées nécessitent un stockage d'observabilité prenant en charge getMetricAggregate. (Default: `'resource'`)

**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): Fenêtre temporelle d'agrégation du coût lorsque la portée 'resource' ou 'thread' est utilisée. S'applique uniquement aux portées autres que 'run'. (Default: `'7d'`)

**strategy** (`'block' | 'warn'`): Stratégie appliquée lorsque la limite de coût est dépassée. 'block' interrompt l'exécution avec une erreur TripWire. 'warn' consigne un avertissement, mais autorise la poursuite de l'étape. (Default: `'block'`)

**message** (`string`): Modèle de message personnalisé pour le motif de l'interruption. Prend en charge les espaces réservés {usage} et {limit}. (Default: `'Cost guard: cost limit exceeded ({usage}/{limit})'`)

## Propriétés de l'instance

**id** (`'cost-guard'`): Identifiant du Processor.

**name** (`'Cost Guard'`): Nom d'affichage du Processor.

**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Fonction de rappel invoquée lorsqu'un dépassement de coût est détecté, quelle que soit la stratégie. Elle fait partie de l'interface Processor généralisée. Utilisez-la pour des effets de bord tels que l'envoi d'alertes, la consignation dans des systèmes externes ou l'envoi d'e-mails aux utilisateurs. Les erreurs levées par cette fonction de rappel sont interceptées silencieusement.

**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Compare le coût cumulé estimé à maxCost avant chaque appel au LLM. Interroge le stockage d'observabilité pour obtenir les données de coût : la portée run filtre selon l'identifiant de Trace, tandis que les portées resource/thread filtrent selon leurs identifiants respectifs et une fenêtre temporelle. Appelle abort() lorsque la limite est dépassée (stratégie block) ou consigne un avertissement (stratégie warn). Les vérifications du coût sont approximatives en raison du délai de persistance des métriques.

## Comportement en cas d'erreur

Lorsque la stratégie `block` est active (par défaut), `CostGuardProcessor` appelle `abort()` avec `retry: false` lorsque la limite de coût est dépassée. Les métadonnées TripWire comprennent :

- `processorId` : `'cost-guard'`
- `usage` : utilisation cumulée actuelle (`estimatedCost`, `costUnit`)
- `maxCost` : limite de coût configurée
- `scope` : portée active (`'run'`, `'resource'` ou `'thread'`)
- `scopeKey` : identifiant de la portée pour les portées resource/thread (le cas échéant)

## Comportement des portées

| Portée     | Suivi sur plusieurs exécutions | Filtre                            | Contexte requis                    |
| ---------- | ------------------------------ | --------------------------------- | ---------------------------------- |
| `run`      | Non                            | `traceId` du span actuel          | Contexte de Tracing (automatique)  |
| `resource` | Oui                            | `resourceId` + fenêtre temporelle | `resourceId` dans `RequestContext` |
| `thread`   | Oui                            | `threadId` + fenêtre temporelle   | `threadId` dans `RequestContext`   |

Toutes les portées nécessitent un stockage d'observabilité prenant en charge `getMetricAggregate`. Si aucun stockage d'observabilité n'est configuré pour l'instance Mastra, une erreur est levée lors de l'enregistrement.

Pour la portée `run`, le Processor lit l'identifiant de Trace dans le contexte de Tracing du span actuel. Si aucun contexte de Tracing n'est disponible, la vérification est ignorée (mode fail-open).

Pour les portées `resource` et `thread`, la vérification est ignorée si l'identifiant de contexte requis est absent lors de l'exécution. Les échecs des requêtes d'observabilité sont traités selon une stratégie fail-open : en cas d'échec d'une requête, le coût est considéré comme nul.

> **Remarque sur le délai de persistance des métriques.** Le pipeline d'observabilité utilise des Exporters avec mémoire tampon qui transmettent les métriques de manière asynchrone. Un court délai sépare la fin d'un appel au LLM du moment où ses métriques de coût peuvent être interrogées. Lors de l'exécution à haute fréquence d'un Agent, la garde de coût peut ne détecter le dépassement d'une limite qu'une ou plusieurs étapes après que le coût réel a franchi le seuil.