Skip to main content

​
Cost Budget Auto-Stop

The CostTracker checks budgets after every tool roundtrip, not just before the loop starts. This prevents a multi-roundtrip agent from blowing through its budget during tool-calling loops.

​
How It Works

When a costTracker is configured on an agent, the onRoundtripComplete loop hook automatically:
  1. Calls checkInProgressBudget() with cumulative token usage (without persisting an entry — no double-counting)
  2. Checks if any budget limit is exceeded
  3. If exceeded, gracefully stops the LLM loop and returns the last assistant message
The actual cost entry is persisted only once at the end of agent.run(), ensuring accurate totals.

​
Configuration

import { Agent, openai, CostTracker } from "@radaros/core";

const tracker = new CostTracker({
  pricing: { "gpt-4o": { promptPer1k: 0.0025, completionPer1k: 0.01 } },
  budget: {
    maxCostPerRun: 0.50,     // $0.50 max per run
    maxTokensPerRun: 100_000, // 100K tokens max per run
  },
});

const agent = new Agent({
  name: "budget-bot",
  model: openai("gpt-4o"),
  costTracker: tracker,
});

​
CostTracker Methods

// Persist a cost entry (called once at end of run)
tracker.track({ runId, agentName, modelId, usage, sessionId, userId });

// Mid-run budget check without persisting (avoids double-counting)
const exceeded = tracker.checkInProgressBudget(modelId, cumulativeUsage, runId);

// Check if budget is exceeded for a completed run
const over = tracker.isBudgetExceeded(runId, sessionId, userId);

// See remaining budget headroom
const { costRemaining, tokensRemaining } = tracker.estimateRemaining(runId);

​
Behavior

ScenarioBeforeAfter
10-roundtrip loop, budget hit at roundtrip 3Budget only checked before loopLoop stops at roundtrip 3
Cost trackingOnly after full loop completesBudget checked each roundtrip, entry persisted once at end
Multi-roundtrip tool callsCould double-count intermediate roundtripscheckInProgressBudget checks without persisting

​
Works Across All Agent Types

Cost auto-stop works with:
  • Agent — Text agents with tool calling
  • VoiceAgent — Tracks realtime API token usage
  • BrowserAgent — Tracks vision model tokens across browser steps