Agent budgets

Applies to: Hosted session and Your runner.

Agents spend money. A budget is a cap you set so they cannot surprise you on the bill. Ithura warns you before the cap and stops new runs at it.

You set budgets in Settings, Agents. Admins can change them. Members can see them.

There is no extra plan requirement. A budget is part of running agents, not a tier above it: if you can register an agent, you can cap it.

What you can set

  • A budget for one agent.
  • A budget for the whole workspace, all agents together.

Each budget has a period, a cap in USD and a warning level.

  • Period: per day or per month. Both reset at 00:00 UTC. A month starts on the 1st.
  • Cap: the most the agent may spend in the period.
  • Warn at: a percent of the cap. The default is 80.

A budget counts what agents and runners spent in the period. Spend from other features, such as Home, is not counted. If the agent has its own budget and the workspace has one too, either one can stop it.

Hosted session

A hosted run also has its own cost cap per run, set on the agent between 0.50 and 50 USD, 10 by default. The run stops at the cap. The spend counted is the run's cost at your AI provider's list price, as shown on the run receipt. Ithura adds no charge. A run that is waiting for budget starts when the sessions running now free up what they hold. See Hosted agent sessions.

A provider can report a few cents for a hosted run after the run has ended. Ithura adds them to that run's receipt, and they count toward the budget period in which they arrive, which can be the next day or month. They never reopen a run that has ended. If they take a budget past its cap, the cap applies to the next run.

Your runner

The runner's cost comes from what the tool reports, or is estimated from tokens. See below.

What is estimated

Runs on a subscription plan have no bill per run. Ithura estimates their cost from the tokens used. When any spend in the period is from a subscription run, the page says "estimated" next to the amount.

When the cap is reached

New runs do not start. The agent shows as paused, with the time it resumes: "Paused until 00:00 UTC", or the date for a monthly budget.

A run that is already working is not stopped. It finishes. Only the next run is held back.

Delegating a task to a paused agent still works for agents that run through ithura-agent: the task waits in the queue, and the agent picks it up after the reset. A hosted agent is refused at once, with a message that says when it resumes.

Raise the cap or remove the budget and the agent can start again right away.

On Home, an agent that cannot start runs is grouped under Paused, with a line that reads "Paused: daily budget reached, resumes 02:00 local (00:00 UTC)". A monthly budget says "monthly" in place of "daily". The reset time is given twice, in your own zone and in UTC, so neither reading has to be worked out.

Who is told

Two events are announced, each once per period:

  • The warning, when spend reaches the warn level.
  • The cap, when spend reaches 100 percent.

Who gets them: the workspace admins, and anyone who delegated a task to that agent in the period.

The notice always lands in the inbox. A push goes out too, unless you turned push off or you are in Do Not Disturb or quiet hours. The notice links to Settings, Agents. Email is off unless you turn on agent-budget-email in your profile settings. Then it goes out in the normal email digest.

At the cap, Ithura also adds one line to the thread of each open task that agent is working on, so the people on the task see why nothing is moving. The warning does not post in threads.

Two limits on that: a task counts as open when it is idle, working or waiting on a person, and at most 25 threads get the line. An agent paused with more than 25 tasks in flight will leave some threads without it, so the inbox notice and the Settings page are the reliable places to look.

A new period starts clean, so both notices can fire again. Changing a budget also starts it clean.

If you run ithura-agent yourself

The agent checks for the pause on each poll. While paused it skips the work and keeps polling, and it logs the pause once. A start that Ithura refuses because of the budget does not count against the agent's own daily run limit. When the period resets, it carries on with the same queue.