Budget
The agent-budget config node defines an optional usage limit. A budget can be
shared by multiple agent nodes, but usage is calculated from stored session or
user records rather than from the config node alone.
Set a positive hard limit: An empty or zero Hard limit is interpreted as
0. When that Budget node is selected, the agent is already at its limit and the first reasoning step is blocked.
Properties
Section titled “Properties”| Property | Purpose |
|---|---|
| Name | Friendly plan or limit label. |
| Period | Session, Daily, Weekly, Monthly, or Lifetime. |
| Limit by | Tokens or Spend in USD. |
| Hard limit | Usage value at which the run stops. |
| Warn at (%) | Optional percentage that emits a warning before the hard limit. |
Periods
Section titled “Periods”| Period | Current scope |
|---|---|
| Session | Current sessionId. |
| Daily | Current user, reset at midnight UTC. |
| Weekly | Current user, reset on Monday UTC. |
| Monthly | Current user, reset on the first day of the UTC month. |
| Lifetime | Current user with no time reset. |
Daily, Weekly, Monthly, and Lifetime budgets require a stable userId to
aggregate usage as intended.
Limit Types
Section titled “Limit Types”Tokens uses prompt and completion usage reported for model calls.
Spend uses cost reported by the provider. If the provider omits or misreports cost, spend tracking cannot be accurate.
Warnings And Stops
Section titled “Warnings And Stops”Budget state is checked before each reasoning step. After recorded usage reaches
the warning percentage, the runtime can emit agent.warning before every
subsequent reasoning step until the hard limit is reached.
When previously recorded usage meets or exceeds the hard limit, the runtime
emits agent.error instead of starting another reasoning step.
Usage is recorded after each model call. A call that crosses the limit has already happened, and a terminal response from that call can still be returned. Thinker normally makes two model calls within one reasoning step, without a budget check between them.
Sharing And Storage
Section titled “Sharing And Storage”Sharing a Budget config node shares its period, limit type, hard limit, and warning setting. It does not by itself create one pooled balance for unrelated agents.
Counters are stored as facts through the Memory selected by the Agent node. Their effective grouping also depends on the logical agent identity, the session or user scope, and the budget period.
Agent Studio Editing
Section titled “Agent Studio Editing”Studio exposes the current Budget fields, but its numeric inputs do not enforce all Node-RED editor constraints. Use a positive Hard limit and a warning percentage below 100, then verify the deployed values in Node-RED.
Choosing A Budget
Section titled “Choosing A Budget”Use a Session budget to contain one unusually expensive conversation. Use a user-period budget for product plans or recurring limits. Test provider usage reporting before relying on a Spend budget in production.