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

# CostGuard 프로세서

그만큼`CostGuardProcessor`구성 가능한 비용 임계값이 초과되면 Agent 루프 전체에 금전적 비용 제한을 적용하고 차단하거나 경고합니다.

각 LLM 호출 전에 비용 한도를 확인하기 위해 `processInputStep`을 사용합니다. 비용 데이터는 모든 범위에서 Observability 스토리지 API(`getMetricAggregate`)를 통해 쿼리됩니다. `resource` 및 `thread` 범위에서는 구성 가능한 기간(기본값 7일) 동안 여러 실행의 비용을 집계합니다. `run` 범위에서는 현재 Trace의 비용을 쿼리합니다. 토큰 기반 제한의 경우 다음을 사용하세요.`TokenLimiterProcessor` instead.

세 가지 범위 지정 모드를 지원합니다.

- **실행 범위**: 추적 ID를 통해 단일 Agent 실행 내 비용을 추적합니다.
- **자원 범위**(기본값): 당 누적 비용을 추적합니다.`resourceId` across runs
- **스레드 범위**: 당 누적 비용을 추적합니다.`threadId` across runs

> **대략적인 비용 가드.** 비용 데이터는 Observability 파이프라인의 버퍼링된 내보내기를 통해 비동기적으로 유지됩니다. 빠르게 실행되는 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` callback:

```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). 양수여야 합니다. Observability 메트릭의 비용 데이터를 사용합니다. 메트릭 유지 지연으로 인해 대략적인 한도입니다.

**scope** (`'run' | 'resource' | 'thread'`): 비용 추적 범위입니다. 'run'은 Trace ID를 통해 현재 Agent 실행 내의 비용을 추적합니다. 'resource'는 여러 실행에서 resourceId별 누적 비용을 추적합니다(기본값). 'thread'는 여러 실행에서 threadId별 누적 비용을 추적합니다. 모든 범위에는 getMetricAggregate를 지원하는 Observability 스토리지가 필요합니다. (Default: `'resource'`)

**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): 'resource' 또는 'thread' 범위를 사용할 때 비용 집계에 적용할 기간입니다. run이 아닌 범위에만 적용됩니다. (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와 비교합니다. Observability 스토리지에서 비용 데이터를 쿼리합니다. run 범위는 Trace ID로 필터링하고 resource/thread 범위는 기간과 함께 각각의 ID로 필터링합니다. 한도를 초과하면 block 전략에서는 abort()를 호출하고 warn 전략에서는 경고를 기록합니다. 메트릭 유지 지연으로 인해 비용 확인은 대략적입니다.

## 오류 동작

`block` 전략이 활성화된 경우(기본값), 비용 한도를 초과하면 `CostGuardProcessor`가 `retry: false`와 함께 `abort()`를 호출합니다. TripWire 메타데이터에는 다음이 포함됩니다.

- `processorId`: `'cost-guard'`
- `usage`: 현재 누적 사용량(`estimatedCost`, `costUnit`)
- `maxCost`: 구성된 비용 한도
- `scope`: 활성 범위(`'run'`, `'resource'` 또는 `'thread'`)
- `scopeKey`: 리소스/스레드 범위의 범위 식별자(해당하는 경우)

## 범위 지정 동작

| 범위                                                                                                                             | 여러 실행에 걸쳐 추적 | 필터                | 필요한 컨텍스트                       |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------ | ----------------- | ------------------------------ |
| `run`                                                                                                                          | 아니요          | 현재 스팬의 `traceId`  | Tracing 컨텍스트(자동)               |
| `resource`                                                                                                                     | 예            | `resourceId` + 기간 | `RequestContext`의 `resourceId` |
| `thread`                                                                                                                       | 예            | `threadId` + 기간   | `RequestContext`의 `threadId`   |
| 모든 범위에는 `getMetricAggregate`를 지원하는 Observability 스토리지가 필요합니다. Mastra 인스턴스에 Observability 스토리지가 구성되어 있지 않으면 등록 시 오류가 발생합니다.     |              |                   |                                |
| `run` 범위의 경우 프로세서는 현재 스팬의 Tracing 컨텍스트에서 Trace ID를 읽습니다. 사용할 수 있는 Tracing 컨텍스트가 없으면 확인을 건너뜁니다(fail-open).                      |              |                   |                                |
| `resource` 및 `thread` 범위에서 런타임에 필요한 컨텍스트 ID가 없으면 확인을 건너뜁니다. Observability 쿼리 실패는 fail-open 전략으로 처리합니다. 쿼리가 실패하면 비용을 0으로 간주합니다. |              |                   |                                |

> **메트릭 지속성 지연에 대한 참고 사항입니다.**&#xAD00;측 가능성 파이프라인은 측정항목을 비동기적으로 플러시하는 버퍼링된 내보내기를 사용합니다. LLM 호출이 완료되는 시점과 해당 비용 지표를 쿼리에 사용할 수 있는 시점 사이에 짧은 지연이 존재합니다. 빈도가 높은 Agent 실행 중에 비용 가드는 실제 비용이 임계값을 초과한 후 하나 이상의 단계가 나타날 때까지 한도 위반을 감지하지 못할 수 있습니다.