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

# CostGuardProcessor

`CostGuardProcessor` 會在 Agent 迴圈中強制套用費用上限，並在超過可設定的費用門檻時封鎖或發出警告。

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

若要設定以 token 為基礎的上限，請改用 `TokenLimiterProcessor`。

支援三種範圍模式：

- **執行範圍**：透過 Trace ID 追蹤單次 Agent 執行內的費用
- **資源範圍**（預設）：依 `resourceId` 追蹤多次執行的累計費用
- **討論串範圍**：依 `threadId` 追蹤多次執行的累計費用

> **概略費用防護。** 費用資料會透過可觀測性管線中的緩衝匯出器，以非同步方式保存。快速執行的 Agent 可能在指標可供查詢前，就已超過設定的上限。請將 `maxCost` 視為概略門檻；快速執行的 Agent 可能會超過此門檻。

## 使用範例

追蹤每個資源的累計費用（預設範圍）：

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

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

以 24 小時的時間範圍追蹤每個討論串的累計費用：

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

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

附加至 Agent，並設定 `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],
  },
})
```

## 建構函式參數

**maxCost** (`number`): 允許的最高預估費用（例如 0.50 表示 0.50 美元）。必須是正數。使用可觀測性指標中的費用資料。由於指標保存會延遲，因此這是概略上限。

**scope** (`'run' | 'resource' | 'thread'`): 費用追蹤範圍。'run' 會透過 Trace ID 追蹤目前 Agent 執行內的費用。'resource' 會依 resourceId 追蹤多次執行的累計費用（預設）。'thread' 會依 threadId 追蹤多次執行的累計費用。所有範圍都需要支援 getMetricAggregate 的可觀測性儲存空間。 (Default: `'resource'`)

**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): 使用 'resource' 或 'thread' 範圍時，用於彙總費用的時間範圍。僅適用於非執行範圍。 (Default: `'7d'`)

**strategy** (`'block' | 'warn'`): 超過費用上限時採取的策略。'block' 會以 TripWire 錯誤中止。'warn' 會記錄警告，但允許該步驟繼續執行。 (Default: `'block'`)

**message** (`string`): 用於中止原因的自訂訊息範本。支援 {usage} 與 {limit} 預留位置。 (Default: `'Cost guard: cost limit exceeded ({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 與時間範圍篩選。超過上限時，block 策略會呼叫 abort()，warn 策略則會記錄警告。由於指標保存會延遲，因此費用檢查是概略值。

## 錯誤行為

啟用 `block` 策略（預設）時，若超過費用上限，`CostGuardProcessor` 會以 `retry: false` 呼叫 `abort()`。TripWire 中繼資料包含：

- `processorId`：`'cost-guard'`
- `usage`：目前的累計用量（`estimatedCost`、`costUnit`）
- `maxCost`：設定的費用上限
- `scope`：目前使用的範圍（`'run'`、`'resource'` 或 `'thread'`）
- `scopeKey`：資源／討論串範圍的範圍識別碼（如適用）

## 範圍行為

| 範圍         | 跨執行追蹤 | 篩選條件                | 必要內容                             |
| ---------- | ----- | ------------------- | -------------------------------- |
| `run`      | 否     | 目前 span 的 `traceId` | 追蹤內容（自動）                         |
| `resource` | 是     | `resourceId` + 時間範圍 | `RequestContext` 中的 `resourceId` |
| `thread`   | 是     | `threadId` + 時間範圍   | `RequestContext` 中的 `threadId`   |

所有範圍都需要支援 `getMetricAggregate` 的可觀測性儲存空間。若 Mastra 執行個體未設定可觀測性儲存空間，系統會在註冊時擲回錯誤。

對於 `run` 範圍，處理器會從目前 span 的追蹤內容讀取 Trace ID。若沒有可用的追蹤內容，則會略過檢查（fail-open）。

對於 `resource` 與 `thread` 範圍，若執行階段缺少必要的內容 ID，則會略過檢查。可觀測性查詢失敗時會採取 fail-open 策略：若查詢失敗，費用會視為零。

> **關於指標保存延遲。** 可觀測性管線使用緩衝匯出器，以非同步方式清空並匯出指標。LLM 呼叫完成後，需要一小段時間，才能查詢其費用指標。當 Agent 高頻率執行時，費用防護可能要等到實際費用超過門檻後的一或多個步驟，才會偵測到超出上限。