Agent Budget

Cost guardrails, spend optimization, and budget management for autonomous AI agents

Features · Install · Quick Start · MCP Setup · Python API · Changelog

Stop runaway LLM costs before they happen. Agent Budget is an MCP server + CLI that gives autonomous AI agents real-time cost guardrails, progressive spend throttling, anomaly detection, model cost optimization, and full budget management — all local, no account required.

┌───────────┐     stdio      ┌───────────────┐     JSON      ┌──────────────┐
│   Agent   │ ─────────────▶ │ agent-budget  │ ────────────▶ │  Guardrail   │
│ (Claude,  │ ◀───────────── │  MCP server   │ ◀──────────── │   Engine     │
│  Cursor…) │  tool result   └───────────────┘  decision     └──────────────┘
└───────────┘                                                    │
                                                                 ▼
                                                    ALLOW / WARN / THROTTLE / BLOCK

Why Agent Budget?

How it compares

Related MCP server: agentbill-mcp

Features

🚨 Cost Guardrails & Kill Switch (v0.5.0)

• Real-time pre-flight checks — check_guardrails() before LLM calls: ALLOW / WARN / BLOCK decisions

• Multi-scope guardrails — Set limits per global, agent, model, budget, or task scope

• Multiple limit types — Daily, hourly, per-call, and monthly spend caps

• Emergency kill switch — Instantly block ALL LLM calls with auto-expire and override tokens

• Cost alert events — Track breaches separately; acknowledge & clear

• Cooldown periods — Block subsequent calls for N minutes after a breach

• Priority ordering — Higher-priority guardrails checked first; most restrictive wins

📉 Progressive Cost Throttling (v0.8.0)

• Tiered spend control — Graduated thresholds (60%, 75%, 90%) instead of binary cutoff

• Cost-per-call limits — Recommends max spend per call at each tier

• Model downgrade suggestions — "Switch to gpt-4o-mini" at 75% spend

• Custom tiers — Define your own threshold percentages and limits

• Advisory → Hard cap — 60% = advisory, 90% = blocks expensive calls

💰 Reserve & Settle Protocol (v0.9.0)

• Concurrency-safe holds — Reserve funds before an operation, settle or release after

• Double-spend prevention — Atomic reserve/settle ensures funds can't be spent twice

• TTL-based expiry — Reserves auto-expire and release funds if not settled

• Partial settlement — Settle for less than reserved; release the remainder

🔮 Spend Projection & Loop Detection (v0.6.0)

• Burn forecast — project_spend() predicts ETA-to-limit based on spend velocity

• Multi-period projections — Daily, hourly, and monthly with confidence scoring

• Guardrail breach prediction — Know if a guardrail will trigger before period ends

• Loop detection — Detect runaway agents making repeated similar LLM calls

• Jaccard similarity — Groups repeated operations by call signature

• Auto-block — Automatically block looping agents for N minutes

🔍 Spend Anomaly Detection (v0.10.0)

• Statistical outlier detection — Flag costs that deviate from historical patterns

• Z-score based — Configurable sensitivity thresholds

• Per-agent / per-model baselines — Learn normal spend patterns

• Real-time alerts — Fire webhook events when anomalies detected

🧮 Model Cost Optimizer (v0.11.0)

• Compare models — Cost-compare your current model against all alternatives

• Smart recommendations — Cheapest viable alternative with rationale + tier analysis

• Savings projection — Monthly savings estimate for model switches

• Capability tiers — High / medium / economy classification with fuzzy matching

• Cheapest-for-tier — Find the cheapest model at or above a capability level

• 30+ models — Built-in pricing for OpenAI, Anthropic, Google, Meta, Mistral, Cohere

🔔 Guardrail Webhooks (v0.7.0)

• Webhook notifications — Fire on guardrail triggers, kill switch, projection breaches

• Event filtering — Subscribe to specific events (warn/block/kill/threshold/loop)

• HMAC-SHA256 signing — Optional secret for request signature verification

• Retry with backoff — Automatic retries on 5xx errors with exponential backoff

• Slack/Discord/PagerDuty ready — Standard JSON POST payloads work out-of-the-box

💱 Multi-Currency FX Engine (v0.13.0)

• Exchange rate management — Set custom rates for any currency pair; overrides take priority

• Automatic inverse derivation — Set EUR→USD, get USD→EUR for free

• USD triangulation — Derive cross-rates (EUR→GBP) from USD-anchored pairs

• Static reference table — 15 major currencies with mid-2025 estimates (zero dependencies)

• Multi-currency summary — Unify budgets, spending, income, and savings into one base currency

• FX rate drift detection — Snapshot rates, update them, then detect which pairs moved beyond a threshold

• Financial impact computation — Quantify the budget impact of FX drift on a specific exposure amount

• Rate change history — Automatic snapshots on rate overwrite; manual snapshots for periodic monitoring

• CLI support — agent-budget fx set|get|list|delete|convert|summary|snapshot|history|drift|clear-history

🔮 Statistical Forecasting & Scenario Engine (v0.14.0)

• Real time-series methods — Moving average, Holt's linear trend (damped), and additive Holt-Winters with seasonality

• Auto method selection — Walk-forward backtesting picks the lowest-MAPE method per budget

• Prediction intervals — Residual-derived bands that widen with √horizon, at 50–99% confidence

• Projected breach scan — Predict which budgets exceed their limits and exactly when, before it happens

• What-if scenarios — Scale spend ±%, override absolute amounts, inject one-off spikes; target all/category/budget

• Saved scenarios — Persist and re-run scenarios against live data; ad-hoc runs supported too

• Cash runway analysis — All-time balance vs. linear-trend monthly burn; exhaustion date + month-by-month projection

• Multi-currency aware — History and forecasts computed in the budget's own currency via the FX engine

• Partial-period safety — The current in-progress period is excluded from history so it can't skew estimates

• 9 new MCP tools — forecast_budget, forecast_all_budgets, get_projected_breaches, backtest_forecast_methods, run_what_if_scenario, analyze_cash_runway, list_scenarios, run_saved_scenario, delete_scenario

• CLI — agent-budget predict forecast|backtest|breaches|runway|scenario|scenarios|run-saved|delete-scenario

📊 Budget Management (v0.1.0–v0.4.0)

• Budget tracking — Create budgets with limits, periods, categories, rollover

• Expense tracking — Log expenses with categories, tags, vendor info, receipts

• Recurring expenses — Schedule payments (daily/weekly/monthly/quarterly/yearly)

• Savings goals — Track progress toward targets with auto-completion

• Spending rules — Block, warn, or require approval for expenses

• Income tracking — Multiple sources, recurring income templates

• Cash flow analysis — Income vs expenses, savings rate, burn rate, runway

• Financial dashboard — Health score (0-100), budget status, sustainability

• Multi-currency — 15+ currencies

• Data export — JSON, CSV, Markdown

Installation

pip install agent-budget

Or with uv:

uv pip install agent-budget

Quick Start

CLI

# Create a monthly budget
agent-budget budget create "API Costs" --limit 500 --period monthly --category api

# Log an expense
agent-budget expense add 25.50 --category api --description "OpenAI GPT-4 call" --vendor "OpenAI"

# Check budget status
agent-budget budget status

# Create a cost guardrail (block at $50/day globally)
agent-budget guardrail create "Daily Cap" global --daily-limit 50.0

# Check before an LLM call
agent-budget guardrail check --cost 0.05 --agent worker-bot --model gpt-4o

# Emergency stop
agent-budget kill-switch trigger "Budget blown — investigating"

# Optimize: find cheaper model
agent-budget optimize recommend --model gpt-4o --input-tokens 1000 --output-tokens 500

MCP Server Setup

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agent-budget": {
      "command": "uvx",
      "args": ["agent-budget", "serve"]
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "agent-budget": {
      "command": "uvx",
      "args": ["agent-budget", "serve"]
    }
  }
}

Continue

~/.continue/config.yaml:

mcpServers:
  - name: agent-budget
    command: uvx
    args: ["agent-budget", "serve"]

Any MCP host

command: uvx, args: ["agent-budget", "serve"]

Programmatic

from agent_budget.mcp_server import mcp
mcp.run()

MCP Tools

Cost Guardrail Tools

Spend Projection & Loop Detection

Statistical Forecasting & Scenarios (v0.14.0)

Model Cost Optimizer (v0.11.0)

Reserve & Settle (v0.9.0)

Budget & Expense Tools

How Guardrails Work

Agent wants to call GPT-4o
    │
    ▼
check_cost_guardrail(cost=$0.05, agent_id="worker-1", model_id="gpt-4o")
    │
    ▼
Guardrail engine checks in priority order:
  1. Kill switch active?  ──────────────────────▶  BLOCK (all calls)
  2. Per-call limit exceeded?  ─────────────────▶  BLOCK
  3. Progressive throttle tier active?  ────────▶  THROTTLE (advisory or block)
  4. Daily/hourly/monthly limit exceeded?  ─────▶  BLOCK
  5. Approaching a limit?  ─────────────────────▶  WARN
  6. All clear  ────────────────────────────────▶  ALLOW
    │
    ▼
Returns: GuardrailDecision {
    action: ALLOW | WARN | THROTTLE | BLOCK,
    reason: "...",
    suggestions: [...],
    throttle_tier: "60%" | "75%" | "90%" | null,
    max_recommended_cost_usd: ...,
    recommended_model: "gpt-4o-mini" | null,
}
    │
    ▼
Agent proceeds, adjusts, or stops

Progressive Throttling Tiers

Instead of a cliff-edge (full speed → hard block), spend degrades gracefully:

Python API

from agent_budget.service import BudgetService
from agent_budget.models import GuardrailScope, GuardrailAction

svc = BudgetService()

# Set up guardrails with progressive throttling
svc.create_guardrail(
    name="Daily agent cap",
    scope=GuardrailScope.AGENT,
    scope_id="worker-bot",
    daily_limit_usd=20.0,
    warn_at_percent=75,
    progressive_throttling=True,  # Enable tiered control
)

# Before each LLM call — check guardrails
decision = svc.check_guardrails(
    estimated_cost_usd=0.05,
    agent_id="worker-bot",
    model_id="gpt-4o",
)

if decision.action in (GuardrailAction.BLOCK, GuardrailAction.KILL):
    print(f"Blocked: {decision.reason}")
elif decision.action == GuardrailAction.THROTTLE:
    print(f"Throttled at {decision.throttle_tier}")
    print(f"Max recommended cost: ${decision.max_recommended_cost_usd}")
    if decision.recommended_model:
        print(f"Consider switching to: {decision.recommended_model}")
elif decision.action == GuardrailAction.WARN:
    print(f"Warning: {decision.reason}")
else:
    make_llm_call()  # Proceed

# Model optimization — find cheaper alternatives
from agent_budget.optimizer import ModelOptimizer

opt = ModelOptimizer()
recommendation = opt.recommend(
    current_model="gpt-4o",
    input_tokens=1000,
    output_tokens=500,
    monthly_calls=10000,
)
if recommendation:
    print(f"Switch to {recommendation.recommended_model}")
    print(f"Save {recommendation.savings_percent:.0f}% per call")
    print(f"Monthly savings: ${recommendation.projected_monthly_savings:.2f}")
    print(f"Rationale: {recommendation.rationale}")

# Reserve & settle — prevent double-spending in concurrent agents
reservation = svc.create_reservation(
    agent_id="worker-bot",
    amount_usd=5.00,
    scope=GuardrailScope.AGENT,
    scope_id="worker-bot",
    ttl_seconds=300,  # Auto-release after 5 min
)
# ... do the operation ...
svc.settle_reservation(reservation.id, actual_amount_usd=4.23)
# Remaining $0.77 is released back

# Burn forecast
proj = svc.project_spend(
    scope=GuardrailScope.AGENT,
    scope_id="worker-bot",
    period="daily",
)
if proj.will_breach_guardrail:
    print(f"⚠️ Will breach in {proj.eta_minutes_to_limit:.0f} min")
    print(f"Recommendation: {proj.recommendation}")

# Emergency kill switch
svc.trigger_kill_switch(reason="Security incident", override_token="admin-only")
# All check_guardrails() now return action=KILL
svc.reset_kill_switch(override_token="admin-only")

Data Storage

All data is stored in JSON files under ~/.agent-budget/ (or the directory specified by the AGENT_BUDGET_DIR environment variable). No external database required.

Supported Currencies

USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BRL, KRW, MXN, SGD, SEK, NZD

Testing

# Run all 914 tests
uv venv .venv
VIRTUAL_ENV=$(pwd)/.venv uv pip install -e ".[dev]"
.venv/bin/python -m pytest -q

Architecture

src/agent_budget/
├── models.py        # Pydantic models (Budget, Expense, Guardrail, ThrottleTier, ...)
├── store.py         # JSON file persistence
├── service.py       # Business logic (BudgetService)
├── llm_costs.py     # Model pricing catalog + cost calculation
├── optimizer.py     # Model cost optimizer (compare, recommend, project)
├── mcp_server.py    # MCP server with 40+ tools
├── api_server.py    # REST API (FastAPI)
└── cli.py           # CLI (click + rich)

Changelog

v0.13.0 — Multi-Currency FX Engine + Drift Detection 💱

• Exchange rate management — set custom rates, auto-derive inverses and cross-rates

• Triangulation via USD — derive any pair from USD-anchored rates

• Built-in static reference table — 15 major currencies with mid-2025 estimates

• Multi-currency summary — unify budgets, spending, income, and savings into one base currency

• FX rate drift detection — snapshot rates, detect which pairs moved beyond a configurable threshold

• Financial impact computation — quantify the budget impact of FX drift on specific exposure amounts

• Rate change history — automatic snapshots on overwrite + manual periodic snapshots

• 10 new MCP tools (6 FX core + 4 drift detection)

• 10 new CLI commands (fx set|get|list|delete|convert|summary|snapshot|history|drift|clear-history)

• 96 new tests (809 total)

v0.12.0 — Session Cost Importer 📥

• Import from Hermes state.db, JSONL transcripts, request dumps

• Auto-sync imported costs to budgets

• 3 new MCP tools

v0.11.0 — Model Cost Optimizer 🧮

• Model comparison, recommendation, savings projection

• Capability tier classification (high/medium/economy)

• 6 new MCP tools, 5 new API endpoints

• 39 new tests (677 total)

v0.10.0 — Spend Anomaly Detection 🔍

• Statistical outlier detection (z-score based)

• Per-agent/model baselines

• Anomaly webhook events

v0.9.0 — Reserve & Settle Protocol 💰

• Concurrency-safe fund reservation

• TTL-based expiry, partial settlement

• Double-spend prevention

v0.8.0 — Progressive Cost Throttling 📉

• Tiered spend control (60%/75%/90%)

• Model downgrade suggestions

• Custom tiers support

v0.7.0 — Guardrail Webhooks 🔔

• Webhook notifications with HMAC signing

• Event filtering, retry with backoff

• Slack/Discord/PagerDuty ready

v0.6.0 — Spend Projection & Loop Detection 🔮

• Burn forecast with ETA-to-limit

• Runaway loop detection with auto-block

v0.5.0 — Cost Guardrails & Kill Switch 🚨

• Real-time pre-flight checks

• Multi-scope, multi-period guardrails

• Emergency kill switch

v0.4.0 — Income & Financial Dashboard 📊

• Income tracking, cash flow, burn rate

• Financial health scoring, REST API

v0.2.0 — Savings & Rules 💰

• Savings goals, budget rollover

• Spending rules, expense receipts

v0.1.0 — Initial Release 🎉

• Budget management, expense tracking

• Multi-currency, data export

License

MIT