Budget Governor

Control agent costs with BudgetGovernor — token limits, cost caps, and warning thresholds.

Quick Start

const agent = defineAgent({
  name: 'budgeted-agent',
  description: 'Cost-controlled agent',
  tools: [myTool],
  llm,
  systemPrompt: '...',
  budget: {
    maxCostUsd: 1.00,
    maxTokens: 100_000,
    warnThreshold: 0.8,
  },
});

agent = define_agent(
    name="budgeted-agent",
    description="Cost-controlled agent",
    tools=[my_tool],
    llm=llm,
    system_prompt="...",
    budget={
        "max_cost_usd": 1.00,
        "max_tokens": 100_000,
        "warn_threshold": 0.8,
    },
)

BudgetConfig

interface BudgetConfig {
  maxTokens?: number;         // Total token limit
  maxInputTokens?: number;    // Input token limit
  maxOutputTokens?: number;   // Output token limit
  maxCostUsd?: number;        // Cost limit in USD
  warnThreshold?: number;     // Warning at this fraction (0-1, default: 0.8)
}

How It Works

The BudgetGovernor tracks usage after every LLM call:

Records input/output token counts
Estimates cost using built-in cost models
Checks for violations (hard limits)
Checks for warnings (soft thresholds)
Stops the run if a violation occurs

BudgetGovernor API

import { BudgetGovernor } from '@ahzan-agentforge/core';

const governor = new BudgetGovernor(budgetConfig, 'claude-sonnet-4-20250514');

governor.recordUsage(1000, 500);  // Record 1000 input, 500 output tokens

const snapshot = governor.snapshot();
// { inputTokens, outputTokens, totalTokens, estimatedCostUsd, steps }

const violation = governor.checkViolation();
// null or BudgetViolation

const warning = governor.checkWarning();
// null or BudgetWarning

BudgetViolation

When a limit is exceeded, the agent stops with a violation:

type BudgetViolation =
  | { type: 'max_tokens'; limit: number; current: number }
  | { type: 'max_input_tokens'; limit: number; current: number }
  | { type: 'max_output_tokens'; limit: number; current: number }
  | { type: 'max_cost_usd'; limit: number; current: number };

BudgetWarning

When usage exceeds the warning threshold:

type BudgetWarning =
  | { type: 'tokens'; usedFraction: number; threshold: number }
  | { type: 'cost'; usedFraction: number; threshold: number };

Next Steps

Cost Models — per-model pricing
Autonomy Policy — tool-level controls