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) :

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 :

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 :

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'

= 'resource'

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.

window?:

'1h' | '6h' | '24h' | '7d' | '30d' | '365d'

= '7d'

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'.

strategy?:

'block' | 'warn'

= 'block'

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.

message?:

string

= 'Cost guard: cost limit exceeded ({usage}/{limit})'

Modèle de message personnalisé pour le motif de l'interruption. Prend en charge les espaces réservés {usage} et {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.