The problem policies solve
When agents make LLM calls, costs accumulate in the background. Without limits, a single runaway agent or a misconfigured loop can burn through a month’s budget in hours. Budget policies let you set hard caps and choose what happens when those caps are hit. Budget policies are a separate module attheauth.policies. theauth.authorize() does not consult them. Call theauth.policies.checkBudget() yourself before an LLM call, and theauth.policies.recordUsage() after it. Nothing is enforced unless your code makes those calls and acts on the result.
theauth.policy is a different thing: the unified policy engine (see Policy engine). Budget policies live on theauth.policies.Data model
Agent this policy applies to. Omit to create a global policy that applies to all agents.
Stored on the policy and usable as a
list() filter. Not used by checkBudget or recordUsage.Stored on the policy and usable as a
list() filter. Not used by checkBudget or recordUsage.BudgetLimits
Maximum token cost units allowed per day. Counters reset when you call
resetDaily().Maximum token cost units allowed per month. Counters reset when you call
resetMonthly().Maximum calls per day, as counted by
recordUsage() (one per call).Maximum calls per month, as counted by
recordUsage() (one per call).Actions
The action only changes whatcheckBudget() returns once a limit is reached (usage greater than or equal to the limit):
throttle, block, and revoke are not distinguished by the code today: all three return allowed: false, and the policy stays triggered until a reset brings usage back under the limit. warn is useful for sending alerts before you start blocking. Set a warn policy at 80% of your limit and a block policy at 100%.
Creating a policy
Checking a budget before a call
CallcheckBudget with an optional speculative tokensCost to see whether this call would exceed any policy. The cost is included in the check but not recorded yet. Call it before your LLM call; authorize() does not do it for you.
checkBudget evaluates every policy that is not disabled (including triggered ones) for the agent, both exact-match and global. It returns at the first policy whose limit is reached. Note that a warn policy that is reached also returns early with allowed: true, so a block policy later in the list is not reported in that call.
Recording usage after a call
CallrecordUsage after the LLM call completes to update the counters.
recordUsage increments callsToday, callsThisMonth, tokensCostToday, and tokensCostThisMonth on every policy that is not disabled and applies to this agent. It also sets a policy to triggered if the new totals reach a limit.
Resetting counters
Nothing resets counters automatically. Schedule these calls yourself. Reset daily counters from a UTC midnight cron job:triggered move back to active if the new totals are within limits.
Listing and updating policies
Combining warn and block
A common pattern: warn at a soft limit, block at the hard limit.warn policy triggers: checkBudget returns allowed: true with the policy attached, and you can send an alert from your own code. At 1000, checkBudget returns allowed: false, and your code is responsible for stopping the call.
Next steps
Lifecycle hooks
Run your own logic around authorization calls.
Cost attribution
Aggregate token costs per agent for billing reports.
Multi-tenant isolation
Policies can carry a tenant ID, but see the caveat above on how they are checked.