budget-agent - npm
npm
Search<br>Sign UpSign In
budget-agent
0.4.8 • Public • Published 12 minutes ago<br>Readme<br>Code Beta<br>0 Dependencies<br>0 Dependents<br>6 Versions<br>budget-agent
Stop runaway AI agents from burning through your API credits. Track cost, tokens, runtime, and steps. Enforce hard budget limits for OpenAI, Anthropic, LangGraph, LangChain, OpenRouter, CrewAI, Mastra, AutoGen, and any LLM workflow.
budget-agent helps developers track AI agent costs , enforce token limits , set spending caps , monitor LLM usage , and prevent runaway OpenAI, Anthropic, and OpenRouter agents from exceeding budget. Works with every provider. Zero vendor lock-in.
Install
npm install budget-agent
Quick start
import { AgentBudget, BudgetError } from 'budget-agent';
const agent = new AgentBudget({<br>apiKey: process.env.OPENROUTER_API_KEY,<br>limits: {<br>maxCostUSD: 0.10,<br>maxSteps: 15,<br>maxTotalTokens: 50_000,<br>maxWallTimeMs: 30_000,<br>},<br>});
const response = await agent.step({<br>model: 'anthropic/claude-sonnet-4-5',<br>messages: [{ role: 'user', content: 'Hello' }],<br>});
console.log(agent.getUsage());
Prevent runaway AI agents
Agent loops multiply LLM costs across every step. Without guardrails, a single loop can burn through your entire API budget in seconds. budget-agent blocks each call before and after it hits your provider -- so you never overspend.
const agent = new AgentBudget({<br>apiKey: key,<br>limits: { maxCostUSD: 0.05, maxSteps: 10 },<br>});
try {<br>while (true) {<br>const res = await agent.step({ model, messages });<br>messages.push(res.choices[0].message);<br>messages.push({ role: 'user', content: 'Continue.' });<br>} catch (err) {<br>if (err instanceof BudgetError) {<br>console.log('Agent stopped:', err.exceeded.reason);
Track LLM costs in production
Get real-time visibility into every API call. See cost per step, total spend, token breakdown, and wall time.
const usage = agent.getUsage();<br>// {<br>// steps: 12,<br>// totalCostUSD: 0.0847,<br>// totalInputTokens: 24300,<br>// totalOutputTokens: 8200,<br>// elapsedMs: 45200,<br>// stepHistory: [...]<br>// }
agent.summary(); // formatted table in console
Set hard budget caps
Every limit is optional. Set only what you need.
limits: {<br>maxCostUSD: 0.05, // total USD across all steps<br>maxSteps: 10, // total LLM calls<br>maxInputTokens: 50000, // input tokens only<br>maxOutputTokens: 10000, // output tokens only<br>maxTotalTokens: 60000, // input + output combined<br>maxWallTimeMs: 60000, // wall clock time in ms
Runtime limits for AI agents
Kill agents that run too long. Set wall time limits to prevent infinite loops from consuming compute and money.
const agent = new AgentBudget({<br>apiKey: key,<br>limits: {<br>maxWallTimeMs: 30_000, // 30 second hard stop<br>maxCostUSD: 1.00,<br>},<br>});
Token usage tracking
Track input tokens, output tokens, and total tokens across every step. Know exactly where your budget goes.
agent.on('step:end', (e) => {<br>console.log(`Step ${e.stepIndex}: ${e.inputTokens} in / ${e.outputTokens} out / $${e.costUSD}`);<br>});
Agent guardrails
Pre-flight checks estimate output cost before the API call. Post-step checks record actual spend. If a limit is hit, the step rolls back and you can retry cleanly.
try {<br>await agent.step({ model, messages });<br>} catch (err) {<br>if (err instanceof BudgetError) {<br>err.exceeded.reason; // 'cost' | 'steps' | 'totalTokens' | 'wallTime'<br>err.exceeded.usage; // full snapshot at cutoff
OpenAI cost tracking
Use budget-agent with the OpenAI SDK to track GPT-4, GPT-4o, and GPT-3.5 costs in real time.
import { AgentBudget } from 'budget-agent';<br>import OpenAI from 'openai';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const agent = new AgentBudget({<br>apiKey: process.env.OPENAI_API_KEY,<br>limits: { maxCostUSD: 0.50 },<br>executor: async (request) => {<br>const completion = await openai.chat.completions.create({<br>model: request.model,<br>messages: request.messages,<br>});<br>return {<br>model: completion.model,<br>usage: {<br>prompt_tokens: completion.usage?.prompt_tokens ?? 0,<br>completion_tokens: completion.usage?.completion_tokens ?? 0,<br>total_tokens: completion.usage?.total_tokens ?? 0,<br>},<br>choices: completion.choices.map(c => ({<br>message: { role: c.message.role, content: c.message.content ?? '' },<br>finish_reason: c.finish_reason ?? 'stop',<br>})),<br>};<br>},<br>});
Anthropic budget limits
Set spending caps on Claude Opus, Sonnet, and Haiku. Track token usage and enforce cost limits for Anthropic models.
const agent = new AgentBudget({<br>apiKey: process.env.ANTHROPIC_API_KEY,<br>limits: { maxCostUSD: 0.25, maxSteps: 20 },<br>executor: async (request) => {<br>const response = await fetch('https://api.anthropic.com/v1/messages', {<br>method: 'POST',<br>headers: {<br>'x-api-key': process.env.ANTHROPIC_API_KEY!,<br>'anthropic-version': '2023-06-01',<br>'content-type': 'application/json',<br>},<br>body: JSON.stringify({<br>model: request.model,<br>messages: request.messages,<br>max_tokens: 1024,<br>}),<br>});<br>const data = await response.json();<br>return {<br>model: data.model,<br>usage: {<br>prompt_tokens: data.usage?.input_tokens ?? 0,<br>completion_tokens:...