Skip to main content

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 at theauth.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.
checkBudget and recordUsage select policies by agentId only: a policy for that exact agent, or any policy whose agentId is empty. A policy created with only userId or tenantId has no agentId, so it is treated as applying to every agent. The userId and tenantId fields are stored and can be used to filter list(), but they do not scope the check.

Data model

string
Stable identifier with a pol_ prefix.
string
default:"undefined (all agents)"
Agent this policy applies to. Omit to create a global policy that applies to all agents.
string
default:"undefined"
Stored on the policy and usable as a list() filter. Not used by checkBudget or recordUsage.
string
default:"undefined"
Stored on the policy and usable as a list() filter. Not used by checkBudget or recordUsage.
BudgetLimits
The numeric thresholds for this policy.
'warn' | 'throttle' | 'block' | 'revoke'
What happens when a limit is exceeded.
'active' | 'triggered' | 'disabled'
Current policy state. ‘triggered’ means a limit has been hit.
BudgetUsage
Running counters for this policy.

BudgetLimits

number
default:"undefined (no daily token limit)"
Maximum token cost units allowed per day. Counters reset when you call resetDaily().
number
default:"undefined (no monthly token limit)"
Maximum token cost units allowed per month. Counters reset when you call resetMonthly().
number
default:"undefined (no daily call limit)"
Maximum calls per day, as counted by recordUsage() (one per call).
number
default:"undefined (no monthly call limit)"
Maximum calls per month, as counted by recordUsage() (one per call).

Actions

The action only changes what checkBudget() 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

Call checkBudget 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

Call recordUsage 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:
Reset monthly counters on the first of each month:
Both reset calls apply to every policy. After a reset, policies that were 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.
When the agent hits 800, the 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.
Last modified on October 9, 2026