跳到主要内容

CostGuardProcessor

CostGuardProcessor 在 agentic loop 中实施费用上限，并在超出可配置的费用阈值时阻止执行或发出警告。

它使用 processInputStep 在每次 LLM 调用前检查费用上限。对于所有作用域，费用数据都通过可观测性存储 API（getMetricAggregate）查询。对于 resource 和 thread 作用域，它会在可配置的时间窗口内汇总多次运行的费用（默认为 7 天）。对于 run 作用域，它会查询当前 trace 的费用。

如需基于 token 的限制，请改用 TokenLimiterProcessor。

支持三种作用域模式：

  • 运行作用域：通过 trace ID 跟踪单次 Agent 运行中的费用
  • 资源作用域（默认）：按 resourceId 跟踪多次运行的累计费用
  • 线程作用域：按 threadId 跟踪多次运行的累计费用

近似费用保护。 费用数据通过可观测性管道中的缓冲 exporter 异步持久化。在指标可供查询之前，快速运行的 Agent 可能已超出配置的上限。请将 maxCost 视为一个近似阈值，快速运行的 Agent 可能会超过该阈值。

用法示例
用法示例的直接链接

按资源跟踪累计费用（默认作用域）：

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

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

使用 24 小时时间窗口，按线程跟踪累计费用：

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

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

使用 onViolation 回调将其附加到 Agent：

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

构造函数参数
构造函数参数的直接链接

maxCost:

number
允许的最大估算费用（例如，0.50 表示 0.50 美元）。必须为正数。使用可观测性指标中的费用数据。由于指标持久化存在延迟，这是一个近似上限。

scope?:

'run' | 'resource' | 'thread'
= 'resource'
费用跟踪的作用域。'run' 通过 trace ID 跟踪当前 Agent 运行中的费用。'resource' 按 resourceId 跟踪多次运行的累计费用（默认）。'thread' 按 threadId 跟踪多次运行的累计费用。所有作用域都要求可观测性存储支持 getMetricAggregate。

window?:

'1h' | '6h' | '24h' | '7d' | '30d' | '365d'
= '7d'
使用 'resource' 或 'thread' 作用域时用于汇总费用的时间窗口。仅适用于非 run 作用域。

strategy?:

'block' | 'warn'
= 'block'
超出费用上限时采用的策略。'block' 会使用 TripWire 错误中止。'warn' 会记录警告，但允许该步骤继续执行。

message?:

string
= 'Cost guard: cost limit exceeded ({usage}/{limit})'
用于中止原因的自定义消息模板。支持 {usage} 和 {limit} 占位符。

实例属性
实例属性的直接链接

id:

'cost-guard'
Processor 标识符。

name:

'Cost Guard'
Processor 显示名称。

onViolation?:

(violation: ProcessorViolation) => void | Promise<void>
检测到费用违规时调用的回调，与采用的策略无关。它是通用 Processor 接口的一部分。可用于告警、记录到外部系统或向用户发送电子邮件等副作用。此回调抛出的错误会被静默捕获。

processInputStep:

(args: ProcessInputStepArgs) => Promise<void>
在每次 LLM 调用前，对照 maxCost 检查累计估算费用。它会查询可观测性存储中的费用数据：run 作用域按 trace ID 筛选，resource/thread 作用域按各自的 ID 和时间窗口筛选。超出上限时，block 策略会调用 abort()，warn 策略会记录警告。由于指标持久化存在延迟，费用检查是近似的。

错误行为
错误行为的直接链接

启用 block 策略（默认）时，如果超出费用上限，CostGuardProcessor 会调用 abort() 并设置 retry: false。TripWire metadata 包括：

  • processorId：'cost-guard'
  • usage：当前累计用量（estimatedCost、costUnit）
  • maxCost：配置的费用上限
  • scope：当前作用域（'run'、'resource' 或 'thread'）
  • scopeKey：resource/thread 作用域的作用域标识符（如适用）

作用域行为
作用域行为的直接链接

作用域跨运行跟踪筛选条件所需上下文
run否当前 span 中的 traceIdtracing context（自动）
resource是resourceId + 时间窗口RequestContext 中的 resourceId
thread是threadId + 时间窗口RequestContext 中的 threadId

所有作用域都要求可观测性存储支持 getMetricAggregate。如果 Mastra 实例未配置可观测性存储，会在注册时抛出错误。

对于 run 作用域，Processor 会从当前 span 的 tracing context 中读取 trace ID。如果 tracing context 不可用，则跳过检查（fail-open）。

对于 resource 和 thread 作用域，如果运行时缺少所需的上下文 ID，则跳过检查。可观测性查询失败时采用 fail-open 策略：如果查询失败，费用会被视为零。

关于指标持久化延迟的说明。 可观测性管道使用缓冲 exporter 异步刷新指标。从一次 LLM 调用完成到其费用指标可供查询之间存在短暂延迟。在高频执行 Agent 时，费用保护可能要等到实际费用超出阈值一个或多个步骤后，才能检测到超限。

On this page