CostGuardProcessor

CostGuardProcessor 會在整個 Agent 循環中限制金錢成本，並在超出可設定的成本門檻時封鎖或發出警告。

它會使用 processInputStep，在每次呼叫 LLM 前檢查成本上限。所有範圍的成本資料均透過可觀測性儲存 API（getMetricAggregate）查詢。對於 resource 及 thread 範圍，它會在可設定的時間範圍內彙總多次執行的成本（預設為 7 日）。對於 run 範圍，它會查詢目前 Trace 的成本。

如要使用以 token 為基礎的限制，請改用 TokenLimiterProcessor。

支援三種範圍模式：

• 執行範圍：透過 Trace ID 追蹤單次 Agent 執行內的成本
• 資源範圍（預設）：按 resourceId 追蹤多次執行的累計成本
• 執行緒範圍：按 threadId 追蹤多次執行的累計成本

近似成本防護。 成本資料會透過可觀測性管道中的緩衝匯出器，以非同步方式保存。快速執行的 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' 範圍時，用於彙總成本的時間範圍。只適用於非執行範圍。

strategy?:

'block' | 'warn'

= 'block'

超出成本上限時採用的策略。'block' 會以 TripWire 錯誤中止；'warn' 會記錄警告，但允許繼續執行該步驟。

message?:

string

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

中止原因的自訂訊息範本。支援 {usage} 及 {limit} 預留位置。

實例屬性

id:

'cost-guard'

處理器識別碼。

name:

'Cost Guard'

處理器顯示名稱。

onViolation?:

(violation: ProcessorViolation) => void | Promise<void>

偵測到成本違規時呼叫的回呼函式，不受策略影響。這是通用 Processor 介面的一部分。可用於發出警報、記錄至外部系統或向用戶傳送電郵等副作用。此回呼函式拋出的錯誤會被靜默攔截。

processInputStep:

(args: ProcessInputStepArgs) => Promise<void>

在每次呼叫 LLM 前，將累計估算成本與 maxCost 比較。它會向可觀測性儲存空間查詢成本資料：執行範圍按 Trace ID 篩選，資源／執行緒範圍則配合時間範圍，按各自的 ID 篩選。超出上限時會呼叫 abort()（block 策略），或記錄警告（warn 策略）。由於指標保存存在延誤，成本檢查只屬近似值。

錯誤行為

使用 block 策略時（預設），若超出成本上限，CostGuardProcessor 會以 retry: false 呼叫 abort()。TripWire 中繼資料包括：

• processorId：'cost-guard'
• usage：目前的累計用量（estimatedCost、costUnit）
• maxCost：設定的成本上限
• scope：目前使用的範圍（'run'、'resource' 或 'thread'）
• scopeKey：資源／執行緒範圍的範圍識別碼（如適用）

範圍行為

範圍	跨執行追蹤	篩選條件	所需內容
run	否	目前 span 的 traceId	Tracing context（自動）
resource	是	resourceId + 時間範圍	RequestContext 中的 resourceId
thread	是	threadId + 時間範圍	RequestContext 中的 threadId

所有範圍均須使用支援 getMetricAggregate 的可觀測性儲存空間。如 Mastra 實例未設定可觀測性儲存空間，系統會在註冊時拋出錯誤。

對於 run 範圍，處理器會從目前 span 的 Tracing context 讀取 Trace ID。如沒有可用的 Tracing context，便會跳過檢查（fail-open）。

對於 resource 及 thread 範圍，如執行時缺少所需的 context ID，便會跳過檢查。可觀測性查詢失敗時會採用 fail-open 策略：如查詢失敗，成本會視為零。

關於指標保存延誤。 可觀測性管道使用緩衝匯出器，以非同步方式清空並匯出指標。LLM 呼叫完成後，其成本指標需要短暫時間才可供查詢。在 Agent 高頻執行期間，成本防護可能要到實際成本超出門檻後的一個或多個步驟，才偵測到超出上限。