Cost Governance

Cost governance policies cap cumulative token and model spend per session or per agent, preventing runaway costs from unconstrained agent execution.

How it works

The CostBudgetEvaluator in the SDK tracks cumulative cost via SessionState.cumulative_cost_usd. On every action, the evaluator compares the running total against the configured budget. When the budget is exceeded, subsequent actions are blocked.

Session starts → cost = $0.00
  model_invoke (gpt-4.1, 3.2k tokens) → cost += $0.48 → under budget → allow
  model_invoke (gpt-4.1, 7.1k tokens) → cost += $1.06 → under budget → allow
  model_invoke (gpt-4.1, 12k tokens)  → cost += $1.80 → $3.34 > $3.00 → BLOCK

Configuration

Dashboard

Navigate to Policies → New policy, select the Cost Budget template.

Key parameters:

• max_cost_usd — the budget ceiling (default: $10.00)
• scope — session (per execution) or agent (cumulative across sessions)

API

curl -X POST https://api.pavri.ai/api/policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "session-cost-cap",
    "type": "Cost Governance",
    "enforcementMode": "Active"
  }'

SDK

Configure a cost budget directly in the SDK config:

from pavri import secure, PavriConfig

agent = secure(agent, config=PavriConfig(
    cost_budget_usd=5.0,
))

Enforcement modes

Mode	Behavior
Active	Blocks actions when budget exceeded. Agent receives PolicyDeniedError.
Shadow	Logs when budget would be exceeded. No blocking. Useful for calibrating thresholds.
Audit	Emits telemetry event on budget breach. Action proceeds.

What the agent sees

When a cost budget blocks an action, the agent receives a structured error:

PolicyDeniedError: Policy denied action 'tool:billing.query'
  (rule=cost-budget-rule, reason='cost budget exceeded: $5.12 >= $5.00')

The error includes the current cost, the budget limit, and the policy/rule that triggered the denial. Agents can handle this gracefully — terminate the session, return a cached result, or notify the operator.

Observability

Cost budget decisions are tracked via:

• pavri_policy_evaluations_total{result="block", policy_type="cost_budget"} — blocked-by-cost counter
• pavri_policy_denials_total{rule_type="cost"} — denial counter
• policy_eval telemetry events in ClickHouse — full decision context for forensic review

Current constraints

• Cost is tracked in-process via SessionState. If the agent process restarts, the session cost counter resets.
• Cost estimates are based on token counts and model pricing tables. Actual cloud billing may differ slightly.
• Per-agent cumulative budgets require the backend to aggregate across sessions — this is tracked for a future sprint.