Skip to main content
A cost budget controls admission of new work. It cannot cancel a request that the provider has already accepted or guarantee the final invoice. Choose a threshold policy for a simple limit on recorded spend. Choose reservation mode when concurrent workers must reserve a conservative amount before a call.

Limit one run

Set a USD threshold in the Agent configuration. Agentium checks the recorded cost before it starts more work.
This shorthand uses a threshold policy in USD. It throws when a known limit blocks new work. Unknown prices remain visible and warn by default. Use the full policy below to block unknown costs, select another currency, or set a shared accounting period.

Set a threshold

Configuration factory: the host supplies a reviewed catalog and a fixed UTC period. Reuse the same period across workers and requests that share a budget.
Attach the tracker to the Agent and pass the required sessionId in the run options. Scope IDs identify accounting records; your application must authenticate and assign them. Threshold mode checks known spend. A long request, concurrent request, delayed usage event, or late background job can cross the limit before the next admission check. The default unknown-cost policy warns and continues, while exposing incomplete accounting.

Reserve across workers

Install the optional pg dependency and use the same Postgres accounting backend for evidence, selected assessments, budget balances, and reservations.
The host must compute a bound that covers the operation’s possible charges, including cache writes, output limits, hosted tools, duration, and applicable minimums. A nominal average cost is not a conservative bound. If you cannot establish a bound, use threshold mode or reject that operation under reservation policy. Before dispatch, the store reserves all applicable scopes atomically. When usage is known, it commits the selected assessment and settles the reservation in one transaction. Competing workers read the same balances. After active work settles, call await tracker.flush() and then await store.close(). The host owns the store connection. Separate archival storage can receive a copy; it does not replace the transaction backend.

Choose scope and outcome

Limits include currency and an explicit start/end period. Do not add different currencies without a separately sourced conversion. Missing required scope IDs are not permission to ignore a limit.

Handle failures and late usage

A timeout does not prove that the provider did no work. Keep an uncertain reservation until the result is reconciled or non-acceptance is established. Time passing alone must not release the hold. An accounting write can fail after the provider has returned an answer. Retry that write with the same IDs. Never repeat successful provider work to repair accounting. A store failure before dispatch can prevent new work. Warning mode must continue execution. Unknown cost must remain visible. Use the typed decision’s reason and scope balances when showing a budget message.

Check the covered boundary

Accounting applies at instrumented request boundaries and to operations carrying the tracker context. Custom adapters and SDKs with hidden retries can expose only an opaque invocation. Paid tools need their own usage evidence and tariff. An attached tracker does not make arbitrary external work observable. Use request output limits, bounded tool rounds, and application concurrency controls alongside accounting. See usage and cost accounting, storage, and migration from v4.