Cap an agent's spend per day, week, or month. Stops runaway agents before they burn the global budget.
Why per-agent budgets?
The Cockpit has a single global monthly budget that covers every LLM call across the site. That works fine until one agent gets stuck in a loop or a curator schedules a daily job they forget about — and the entire budget evaporates on a single agent while everything else starves.
Per-agent cost guards solve this. Each agent can have an optional daily, weekly, and monthly spending cap. When the agent's actual spend in that period reaches the cap, both manual runs and scheduled runs bail out before another LLM call is made.
Setting the caps
Open any agent's detail page and find the Cost guards (USD) card under the schedule section. All three fields are optional — leave a field blank to mean "no cap for that period".
| Field | Period | Resets |
|---|---|---|
| Daily | Since 00:00 today (local time) | Midnight |
| Weekly | Rolling 7 days | Continuously — the oldest run drops off after 7 days |
| Monthly | Since the 1st of the current calendar month | First of the month |
The caps are independent. If you set daily=1 and monthly=10, the agent can spend $1 per day for 10 days before any cap trips. Either limit alone is enough to stop a run.
How the check works
The guard runs as a pre-flight check in three places:
runAgent(manual or API runs) — checks the budget before the LLM call. If exceeded, throws a clear error with the period and amount.scheduler(scheduled runs) — checks before each due agent. Skips the run and logs which period tripped, so you can see the skip in instrumentation logs.runWorkflow— each step's agent is independently budget-checked before its LLM call.
The cost number used is the agent's actual analytics spend for the period (summed from recordRun entries), not an estimate. So the cap reflects what's already been spent, not what might still be spent on the current run.
Error messages
When a manual run hits a cap, the API returns a 500 with a message like:
Agent "Content Writer" has reached its daily budget ($1.5234 of $1.50 cap). Increase the cap on the agent's settings page or wait for the period to reset.
The scheduler logs the same message and skips the run silently — it does not fire a agent.failed webhook for budget-skip cases, because nothing actually failed.
Recommended values
Sensible starting points:
- Daily $0.50 — fine for a once-a-day blog writer producing one post.
- Weekly $5 — covers a few re-runs or tweaks during the week.
- Monthly $20 — generous monthly safety net.
If you have an image-generating agent, bump the daily cap by ~$0.04 per image you expect per run. Nano Banana is currently $0.039 per image.
Interaction with the global Cockpit budget
Per-agent caps do not replace the global Cockpit monthly budget — they layer on top. The scheduler checks both:
- Global Cockpit budget (95% headroom rule, legacy)
- Per-agent budget (Phase 4)
Whichever trips first stops the run. So an agent without per-agent caps still gets stopped by the global cap, and an agent with per-agent caps can be stopped early before the global cap is anywhere near.
See also
- Performance dashboard — historical cost and run data per agent.
- Agent feedback loop — corrections that reduce per-run cost over time.