> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade to Agentium 4.5

> Move from run-level price estimates to per-attempt usage evidence, exact charges, and explicit unknown costs.

Agentium 4.5 keeps cost accounting in `@agentium/core`. Set `cost: true` and read `result.costs`, or keep an existing shared `CostTracker`. Use asynchronous tracker queries for history. This release changes the accounting read path and token meanings described below.

Install matching versions of the Agentium packages your application uses:

```bash theme={null}
npm install @agentium/core@4.5.0
```

Read the [v4 migration](/migration-v4) first if you are upgrading from 3.x.

## Change the cost read path

Earlier releases often used `tracker.getSummary().totalCost` as a final bill. That estimate could treat a missing model price as zero. It could also add reasoning tokens to output tokens that already included them.

Enable accounting once and read `result.costs` after each run. Agentium handles the writes needed for the run snapshot.

```typescript theme={null}
import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-6.1-sol"),
  cost: true,
});

const result = await agent.run("Explain the result.");
console.log(result.costs);
await agent.close();
```

Set `OPENAI_API_KEY` before running this example. It makes a paid provider request. For an existing shared tracker, keep `costTracker: tracker`; the run result exposes the same cost snapshot. Use `tracker.queryCosts()` for history queries across runs or sessions.

| Field | Meaning |
| - | - |
| `knownSubtotal` | Exact decimal amount for priced charges |
| `total` | Exact decimal amount when complete; otherwise `null` |
| `pricingStatus` | `complete`, `partial`, or `unpriced` |
| `unpricedCount` | Number of charges that lack enough usage, context, or price data |
| `asOf` | Time of the query snapshot |
| `finality` | Whether the selected accounting records are final or provisional |

Do not replace `null` with zero. A known subtotal is not the final total. Background work can add later observations; read a new snapshot after the work and accounting writes have settled.

## Correct the token meaning

Canonical input contains ordinary input, cache reads, and cache writes. Canonical output includes reasoning. Providers report these categories differently, so normalization runs before price calculation.

| Example | Correct result |
| - | - |
| 19 input; 16 output, including 9 reasoning | 35 tokens; one output charge |
| 15,000 inclusive input; 12,000 cache reads; 2,000 cache writes | 1,000 ordinary input; price all three input categories separately |
| Anthropic ordinary input 1,000; reads 12,000; writes 2,000 | 15,000 canonical input |
| Cache writes split between 5 minutes and 1 hour | Price the two buckets; do not also charge their total |

Reasoning and modality details are not automatically extra billable tokens. A text/audio split or cache split must form a valid partition before separate rates apply.

## Replace unscoped price assumptions

`CostTracker({ pricing })` configures only the legacy synchronous projection. It does not override canonical Agent accounting. Move those overrides to `CostTracker({ catalog })`.

Use a versioned catalog for canonical accounting. A rule identifies the billing provider, model or resource, API, meter, unit, currency, and applicable context. Custom deployments and gateways need their own explicit mapping.

* Supply separate rates for ordinary input, cache read, cache write, and output.
* Use the actual returned service tier. A request for Fast can use a different tier.
* Treat Pro mode as reported model work. Do not apply a universal Pro multiplier.
* Apply context bands, cache duration, regional rates, and account terms only where the provider defines them.
* Retain the rule snapshot with the charge. A catalog update does not rewrite historical assessments.

See [cost accounting](/cost/overview) for a complete custom tariff and the `charges` workflow.

## Review storage and budgets

The default store is local memory. Choose an accounting store when costs must survive a restart. The general session `StorageDriver` does not supply the transaction contract required for shared budget reservations.

Threshold budgets check recorded spend. Accepted requests can finish after the threshold is crossed. Reservation budgets need a conservative bound and an atomic accounting backend. Neither mode guarantees the provider's final invoice.

Zero is a real limit. Warning mode continues execution. Unknown cost remains visible and follows the configured unknown-cost policy. Read [budget controls](/features/cost-autostop) before changing a production policy.

## Update event consumers

Use canonical usage and assessment events when you need call evidence and pricing completeness. Deduplicate stable IDs and use the selected assessment revision.

The legacy `cost.tracked` event remains a replacement run total for complete known costs. Do not sum each replacement or add it to canonical attempt charges. Parent and child summaries can describe the same underlying work.

## Keep legacy methods bounded

`track()` remains a synchronous compatibility method. `getEntries()` and `getSummary()` can read that local legacy projection. Once a tracker receives canonical accounting records, those two read methods throw `IncompleteCostError`. Use `queryUsage()` and `queryCosts()` for Agent accounting. This prevents a legacy projection from displaying zero while the ledger contains spend.

Persisted summaries from earlier releases do not contain the evidence needed to reconstruct missing attempts, cache writes, service tiers, or rule snapshots. Keep them labelled as historical estimates. Do not invent those fields during migration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.