Cost Auto-Stop - Agentium

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:

Calls checkInProgressBudget() with cumulative token usage (without persisting an entry — no double-counting)
Checks if any budget limit is exceeded
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 "@agentium/core";

const tracker = new CostTracker({
  pricing: {
    "gpt-6.1-sol": { promptPer1k: 0.002, completionPer1k: 0.01 },
    "gpt-6-luna": { promptPer1k: 0.0001, completionPer1k: 0.0005 }, "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(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
  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

Scenario	Before	After
10-roundtrip loop, budget hit at roundtrip 3	Budget only checked before loop	Loop stops at roundtrip 3
Cost tracking	Only after full loop completes	Budget checked each roundtrip, entry persisted once at end
Multi-roundtrip tool calls	Could double-count intermediate roundtrips	`checkInProgressBudget` 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