agent-budget-guard

Budget-aware degradation for autonomous AI agents — map a spend balance to survival tiers, enforce per-call, hourly and daily LLM inference budgets, and automatically downgrade the model when funds run low.

0 runtime dependencies TypeScript · strict MIT Node >= 20

View on GitHub Quick start

Survival tiers

Turn a cents balance into a tier with configurable thresholds. Zero credits stays alive; only debt is dead.

Budget enforcement

Deny inference calls before they spend — per-call ceiling, hourly, daily and session budgets, any cost store.

Auto model downgrade

Fall back to a cheaper model as funds run low instead of stopping the agent dead.

Survival tiers

A balance in cents maps to one of five tiers, in descending order:

Thresholds are defaults you can override, and the cheap-model name used below the healthy tiers is a config option (defaulting to gpt-5-mini).

Install

npm i github:Princeu3/agent-budget-guard

npm-registry release coming soon.

Quick start

import {
  getSurvivalTier,
  getModelForTier,
  TierManager,
  InferenceBudgetTracker,
  DEFAULT_MODEL_STRATEGY_CONFIG,
} from "agent-budget-guard";

getSurvivalTier(650); // "high"
getSurvivalTier(0);   // "critical" (broke but alive)
getSurvivalTier(-5);  // "dead"

const budget = new InferenceBudgetTracker({
  ...DEFAULT_MODEL_STRATEGY_CONFIG,
  perCallCeilingCents: 50,
  hourlyBudgetCents: 500,
});
budget.checkBudget(40); // { allowed: true }

Attribution

Extracted, refactored and decoupled by Prince Upadhyay from the MIT-licensed Conway-Research/automaton project.