Class: SpendBudget
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:94
A budget for a run of calls; pass one instance to every call that should share it.
Constructors
Constructor
new SpendBudget(
options):SpendBudget
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:107
Parameters
options
The budget's settings.
Returns
SpendBudget
Throws
When maxCostUSD, or a maxTotalTokens that is set, is not a number zero or more.
maxCostUSD may be Number.POSITIVE_INFINITY (a budget with no dollar cap).
Properties
id
readonlyid:string
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:96
The id its spending is kept under.
options
readonlyoptions:Readonly<SpendBudgetOptions>
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:98
Its settings.
Methods
assertCanSpend()
assertCanSpend(
estimateUSD,estimateTokens,what,model?):void
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:167
Refuses (or warns about) a call that could cost up to estimateUSD and use up to estimateTokens, when it would
pass what is left; estimateUSD undefined means the model has no price row, which unpriced: 'allow' checks as
a call that costs nothing. model, the call's provider and model, is named in the refusal of a model with no
price row. A budget with a parent has the parent check the call first, with the same estimate, so the refusal
thrown can be the parent's, or that of a budget above it.
Parameters
estimateUSD
number | undefined
estimateTokens
number
what
string
model?
modelId
string
providerId
string
Returns
void
Throws
At a cap. Its capType, currentCost and limit are those of the cap that refused
the call: the id's total for the session or the day and that cap, or, at the guard's single-operation cap, the
call's estimate and that cap. The token cap has no cap type of its own, so its refusal carries session, the
run's dollars and maxCostUSD, and a message that names the token cap and the token counts.
Throws
For a model with no price row, unless the budget allows one.
record()
record(
costUSD,tokens,what):void
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:227
Records a finished call: its cost (undefined for a model with no price row, counted as nothing) and its tokens. A
token count the provider reported as NaN counts as none: added, it would make the count NaN, and a count of NaN
never reaches maxTotalTokens, since every comparison with NaN is false. A budget with a parent records the call
there too, after itself.
Parameters
costUSD
number | undefined
tokens
number
what
string
Returns
void
recordExternal()
recordExternal(
costUSD,kind):void
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:241
Records a cost made outside AgentOS, such as speech-to-text minutes billed by the minute. A cost of zero or below
records nothing. A budget with a parent records the cost there too, after itself.
Parameters
costUSD
number
kind
string
Returns
void
Throws
When costUSD is not a number, NaN included: a cost that could not be counted would let
the run spend past its cap.
remaining()
remaining():
object
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:148
What is left under this budget's own caps (a parent's are not counted): the dollars under maxCostUSD (Infinity
for a budget with no dollar cap) and, when maxTotalTokens is set, the tokens under it. Never below zero: a record
is never refused, so a run can pass a cap by its last call.
Returns
object
tokens?
optionaltokens:number
usd
usd:
number
spentUSD()
spentUSD():
number
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:134
What the run has spent, in US dollars, as the guard holds it.
Returns
number
tokensUsed()
tokensUsed():
number
Defined in: packages/agentos/src/api/runtime/spendBudget.ts:139
The tokens this budget has counted.
Returns
number