Autonomic Agent token budgets
Autonomic Agents consume LLM tokens (total_tokens: input + output) on every durable wake and every delegated specialist run. Token budgets cap that spend per UTC calendar week and calendar month, at the organization (tenant) and optionally per agent.
Document information
| Field | Value |
|---|---|
| Canonical URL | /docs/07_ai-agents-and-mcp/25_autonomic_agent_token_budgets |
| Version (published date) | 2026-08-27 |
| Tags | ai, agents, autonomic, tokens, subscription |
This quota applies only to Autonomic Agent LLM turns. It does not cap Trace AI interactive chat or ProcessFlow LLMCallLogs.
Tenant cap (subscription)
The organization weekly and monthly caps come from the subscription plan, not from a tenant-admin setting.
| Feature code | Period |
|---|---|
autonomic_tokens_per_week | UTC ISO-8601 week YYYY-Www (Monday 00:00 UTC) |
autonomic_tokens_per_month | UTC calendar month YYYY-MM |
Convention: -1 (or a missing feature) means unlimited. Tenant administrators cannot raise these caps. Platform operators set numbers on the plan. When usage of a finite tenant cap reaches 90%, the Agents console shows a link to Organization settings → Subscription (/organization-settings?tab=subscription). That upgrade prompt is not shown for unlimited tenant caps, or when only a per-agent cap is tight while the organization still has headroom.
Per-agent cap
On Agents → Edit, tenant admins can set:
| Field | Empty | 0 | Positive integer |
|---|---|---|---|
| Weekly token limit | No per-agent weekly cap (shared tenant pool) | Block this agent for the week | Cap that agent; must be ≤ the tenant weekly cap |
| Monthly token limit | No per-agent monthly cap | Block this agent for the month | Cap that agent; must be ≤ the tenant monthly cap |
Runtime uses min(agent cap, tenant cap) for each period, so a plan downgrade takes effect immediately. The sum of agent caps may exceed the tenant cap; agents share the pool first-come.
When a budget is reached
New wakes are refused before the LLM turn with TOKEN_BUDGET_EXHAUSTED (HTTP 409 on a direct run). The in-flight turn that crosses the line may finish (one-turn overshoot). Tenant admins get one in-app notification per scope (tenant or agent) and period.
Triggered wakes are discarded, not deferred. The next schedule tick or a new event after the calendar period resets is a new wake. Discarded wakes write a failed agent_runs row (tokens_used: 0) so you can inspect them on Runs. Mailbox messages for a discarded durable wake are acknowledged so they do not re-fire immediately.
Periods reset by calendar: a new YYYY-Www or YYYY-MM starts at zero. There is no cron.
Spend report
The Agents page shows current-period tenant totals and a per-agent weekly/monthly history. Organization Usage also lists autonomic_tokens_per_week and autonomic_tokens_per_month when those features exist on the plan.