Budgets

A budget caps what an agent may spend — dollars, tokens, model calls, tool calls, sandbox seconds — for one run, a session, the agent, or the whole application. By the end of this page you will have a run that stops before a model call it cannot afford, waits for a person to top it up, and carries on.

Every output on this page is what the code printed when it was run. Prices and the model’s wording will differ on your run.

A run that waits for money

import asyncio
from omnicoreagent import OmniCoreAgent

def show(budgets):
    for b in budgets:
        print(f"  {b['scope']:8} {b['meter']:15} limit {b['limit']:g}  granted {b['granted']:g}  "
              f"spent {b['spent']:.6f}  remaining {b['remaining']:.6f}")

async def main():
    agent = OmniCoreAgent(
        name="writer",
        system_instruction="Answer in plain text.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini", "max_tokens": 300},
        agent_config={
            "governance_config": {
                "budgets": {
                    "request": [{"meter": "model_cost_usd", "limit": 0.0005}],
                    "session": [{"meter": "model_calls", "limit": 20}],
                },
            },
        },
    )
    result = await agent.run("In two sentences, why do budgets matter for agents?")
    print("status:", result["status"])
    request = result["budget_request"]
    print(f"{request['scope']} {request['meter']}: limit {request['limit']}, used {request['used']}, "
          f"needed {request['needed']:.6f}, short {request['shortfall']:.6f}")
    show(await agent.budget_status(result["run_id"]))

    await agent.grant_budget(result["run_id"], approver="alice", amount=0.01, note="demo")
    resumed = await agent.resume(result["run_id"])
    print("status:", resumed["status"])
    print(resumed["response"])
    show(await agent.budget_status(result["run_id"]))
    await agent.cleanup()

asyncio.run(main())

status: awaiting_budget
request model_cost_usd: limit 0.0005, used 0.0, needed 0.001628, short 0.001128
  request  model_cost_usd  limit 0.0005  granted 0  spent 0.000000  remaining 0.000500
  session  model_calls     limit 20  granted 0  spent 0.000000  remaining 20.000000
status: success
Budgets matter for agents because they keep actions constrained to available resources like time, tokens, money, or compute, preventing waste and runaway behavior. They also force prioritization, helping agents choose the most valuable steps and finish tasks reliably within limits.
  request  model_cost_usd  limit 0.0005  granted 0.01  spent 0.001321  remaining 0.009179
  session  model_calls     limit 20  granted 0  spent 1.000000  remaining 19.000000

The first call was priced at $0.001628 — its input, plus 300 output tokens at `max_tokens` — which did not fit in $0.0005. Nothing was spent and no call was made: not even the session’s call counter moved. Alice granted $0.01, the run resumed, and the call really cost $0.001321.

How it works

Every scope that covers the run is charged

A run charges its own request budget, its session’s, its agent’s, and the application’s. Any one of them running out stops the work, and the run says which.

A model call is held before it is made

The runtime counts the input it is about to send and prices the most the call could return: model_config["max_tokens"], or 4,096 tokens when none is set (sent to the provider as the call’s ceiling, so an answer that reaches it ends with termination_reason length). That amount is held, and the call is counted against model_calls. If it does not fit, the call is not made. A hold larger than the whole limit never fits: raise the limit (or lower max_tokens), since topping up by the shortfall covers only that one call.

The real cost replaces the hold

When the call returns, the hold is settled at what it really cost and its tokens are counted. The trace records a budget_warning when a meter reaches warn_at (80%) of its limit plus anything a person granted, and budget_exhausted when it runs out.

At the wall: pause or end

With on_exhausted: "pause" (the default) the run returns status: "awaiting_budget" with a budget_request, keeping the work done so far. With "terminate" it ends with status: "error" and termination_reason: "budget_exhausted".

Counters live in the agent’s memory store, next to its run records. Every change is one atomic operation inside the store, with the limit check in the same step as the increment (one guarded UPDATE in SQL, one script in Redis, one filtered update in MongoDB), so workers sharing a Redis, SQL or MongoDB store share a budget, two of them cannot both spend the last dollar, and a hundred runs charging one application budget at once do not fail each other. Each hold is a record of its own, removed when the call settles. With the default in-memory store, a budget lasts as long as the process. A finished run’s own request counter is removed and its spend kept on the run’s record; session, agent and application counters stay. Counters written by 0.5.x are read and moved into this layout the first time their key is touched; nothing is lost, and nothing needs to be run.

A charge for work already done never fails the run

A hold before a call can refuse the call: that is the budget doing its job. But once a model call or a tool call has happened, recording its charge cannot undo it, so a failed write does not fail the run. The write is tried again for up to 15 seconds; if the store is still unreachable, the charge is kept as unrecorded: on the run’s record (unrecorded_charges), in the trace as a budget_charge_unrecorded event, and as unrecorded in budget_status and GET /runs/{run_id}/budget. The counters then under-count by that amount, and the record is where to find out by how much. Any hold the run left standing is released when it ends.

Scopes, meters and windows

agent_config = {
    "governance_config": {
        "budgets": {
            "application_id": "support-desk",
            "application": [{"meter": "model_cost_usd", "limit": 20.0, "window": "day"}],
            "agent": [{"meter": "sandbox_seconds", "limit": 3600, "window": "day"}],
            "session": [{"meter": "model_tokens", "limit": 200000}],
            "request": [
                {"meter": "model_cost_usd", "limit": 0.50},
                {"meter": "tool_calls", "limit": 40, "on_exhausted": "terminate"},
            ],
        },
    },
}

Scope	Counts	Keyed by
`request`	One run, resumes included	the `run_id`
`session`	Every run with the same `session_id`	the `session_id`
`agent`	Every run of this agent	the agent’s `name`
`application`	Every agent that names the same `application_id` (required for this scope)	`application_id`

Meter	Counts	Checked
`model_cost_usd`	Dollars, from the provider’s published prices	before each call (held), settled after
`model_calls`	Model calls	before each call
`model_tokens`	Tokens in and out	before each call (its input must fit), counted after
`tool_calls`	Tool calls	once, when each runs
`sandbox_seconds`	Seconds a sandbox session is open	before each command, and when the session closes
`subagent_runs`	Workers started with `spawn_subagents`	as each starts

A window resets a counter: total (never), day (00:00 UTC) or month (the 1st, 00:00 UTC).

A call’s output is known only when it returns, so a call can cross a token limit: what it used is still counted in full, and the next call is stopped before it is made (its input would not fit). Leave a call’s worth of headroom if the limit must never be passed. (In 0.4.1 the call that crossed the limit was not counted, and resuming made it again.)

Every field, default and meter is in the budgets reference. Budgets can also live in a JSON policy file, under its "budgets" key (policy reference); set them in one place or the other, not both: both is refused when the agent is built (for a policy file, at its first run, when the file is read).

On a policy object

A policy you build in code carries its budgets in policy.budgets, a PolicyBudgets with one list of BudgetLimits per scope. They become part of the policy and are hashed with it, like budgets in a policy file:

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry
from omnicoreagent.governance import BudgetLimit, PolicyBudgets, build_default_policy

tools = ToolRegistry()

@tools.register_tool("get_weather")
def get_weather(city: str) -> dict:
    """Get the current weather for a city."""
    return {"city": city, "temperature": "25C"}

policy = build_default_policy("permissive-dev")
policy.budgets = PolicyBudgets(
    request=[BudgetLimit(meter="tool_calls", limit=2, on_exhausted="terminate")],
    session=[BudgetLimit(meter="model_calls", limit=20)],
)

async def main():
    agent = OmniCoreAgent(
        name="weather",
        system_instruction="Call get_weather once per city. Answer in plain text.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
        agent_config={"governance_config": {"policy": policy}},
    )
    result = await agent.run("What is the weather in Lagos, Accra and Nairobi?")
    print(result["status"], "|", result["termination_reason"])
    for b in await agent.budget_status(result["run_id"]):
        print(f"  {b['scope']:8} {b['meter']:12} limit {b['limit']:g}  spent {b['spent']:g}")
    await agent.cleanup()

asyncio.run(main())

error | budget_exhausted
  session  model_calls  limit 20  spent 1
  request  tool_calls   limit 2  spent 2

BudgetLimit takes the same fields as a dict limit (meter, limit, window, warn_at, on_exhausted), and PolicyBudgets the same keys as governance_config["budgets"] (request, session, agent, application, application_id). A policy that has budgets takes no governance_config["budgets"] as well.

When a budget runs out

Pause, then grant or deny

budget_request says what stopped the run:

Field	What
`scope`, `meter`, `window`	Which budget
`limit`	Its configured limit
`granted`	What people granted it before (the budget allows `limit` plus this)
`used`	Spent and held so far
`needed`	What the call that stopped needs
`shortfall`	How much more the budget needs for that call
`request_id`	The request to answer (the latest pending one when omitted)

Then, from this process or any other sharing the memory store:

await agent.grant_budget(run_id, approver="alice", amount=..., note=...) adds to that one budget. A grant belongs to the run, not to the call that stopped: it raises the run’s limit by amount, and every later call draws on it until it is used up. Without amount, the grant is exactly the shortfall, enough for the call that stopped and nothing more, so a run that stops one call at a time (a limit of one tool call, say) asks again at each. Name an amount that covers the work still to do, and the run asks once. The policy is not changed; the grant is recorded with the approver’s name.
await agent.deny_budget(run_id, approver="alice", note=...) refuses it.
await agent.resume(run_id) then continues a granted run, or ends a denied one cleanly.
await agent.budget_status(run_id) lists every budget covering the run: limit, granted, spent, reserved, unrecorded and remaining.

End instead of waiting

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry

tools = ToolRegistry()

@tools.register_tool("get_weather")
def get_weather(city: str) -> dict:
    """Get the current weather for a city."""
    return {"city": city, "temperature": "25C"}

async def main():
    agent = OmniCoreAgent(
        name="weather",
        system_instruction="Call get_weather once per city. Answer in plain text.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
        agent_config={
            "governance_config": {
                "budgets": {"request": [{"meter": "tool_calls", "limit": 2, "on_exhausted": "terminate"}]},
            },
        },
    )
    result = await agent.run("What is the weather in Lagos, Accra and Nairobi?")
    print(result["status"], "|", result["termination_reason"])
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())

error | budget_exhausted
This run stopped because the request budget is exhausted: The request budget for tool_calls is exhausted: 2 of 2 used, 1 more needed

Use terminate where no person is watching: batch jobs, evaluations, a background worker. A budget a person has already denied for this run is not asked about again: the run ends.

A model with no published price

A model behind base_url (vLLM, LM Studio, a gateway) usually has no published price. Its calls are made and recorded, but a model_cost_usd budget cannot govern them: it would never trip. Budget its calls and tokens instead. Here against a local OpenAI-compatible server (a small stand-in that gives the same answer to every question):

import asyncio
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="local_model",
        system_instruction="Answer in one sentence.",
        model_config={"provider": "openai", "model": "qwen3-coder-30b", "base_url": "http://localhost:8000/v1"},
        agent_config={
            "governance_config": {
                "budgets": {"session": [
                    {"meter": "model_calls", "limit": 2},
                    {"meter": "model_tokens", "limit": 50000},
                ]},
            },
        },
    )
    for turn in range(1, 4):
        result = await agent.run("What is the largest city in Nigeria?", session_id="demo")
        print(turn, result["status"], "|", result["response"])
        if result["status"] == "success":
            totals = (await agent.get_trajectory(result["trace_id"]))["totals"]
            print("  cost:", totals["estimated_cost_usd"], "| cost_complete:", totals["cost_complete"])
    request = result["budget_request"]
    print(request["scope"], request["meter"], "limit", request["limit"], "used", request["used"])
    await agent.cleanup()

asyncio.run(main())

1 success | Lagos is the largest city in Nigeria.
  cost: 0.0 | cost_complete: False
2 success | Lagos is the largest city in Nigeria.
  cost: 0.0 | cost_complete: False
3 awaiting_budget | None
session model_calls limit 2.0 used 2.0

The third run stopped before its call. cost_complete: False says the 0.0 is not a real price, and the trace has a budget_cost_incomplete event for each such call.

Over HTTP

OmniServe has the same flow. This server (on port 8123, beside the stand-in model on 8000) allows one model call per session:

from omnicoreagent import OmniCoreAgent
from omnicoreagent.serve import OmniServe, OmniServeConfig

agent = OmniCoreAgent(
    name="served",
    system_instruction="Answer in one sentence.",
    model_config={"provider": "openai", "model": "qwen3-coder-30b", "base_url": "http://localhost:8000/v1"},
    agent_config={
        "governance_config": {
            "budgets": {"session": [{"meter": "model_calls", "limit": 1}]},
        },
    },
)

if __name__ == "__main__":
    OmniServe(agent, config=OmniServeConfig(port=8123)).start()

The first question in session demo was answered; the second returned "status": "awaiting_budget" with its run_id and budget_request:

curl -s localhost:8123/run/sync -H 'content-type: application/json' \
  -d '{"query": "Which city is the largest in Nigeria?", "session_id": "demo"}'
curl -s localhost:8123/runs/$RUN_ID/budget

GET /runs/{run_id}/budget returns budgets (as budget_status) and requests (each time the run ran out). Its budget entry and the request’s status:

{'scope': 'session', 'meter': 'model_calls', 'window': 'total', 'key': 'session:demo:total', 'limit': 1.0, 'granted': 0.0, 'spent': 1.0, 'reserved': 0.0, 'unrecorded': 0.0, 'remaining': 0.0}
['pending']

A person grants (or sends "decision": "deny"), and the run is resumed:

curl -s -X POST localhost:8123/runs/$RUN_ID/budget -H 'content-type: application/json' \
  -d '{"decision": "grant", "approver": "alice", "amount": 5, "note": "more questions today"}'
curl -s -X POST localhost:8123/runs/$RUN_ID/resume

{"run_id":"run_816dd331f5c74a9cbc23f9098f5b1fab","request_id":"budgetreq_7a68f7ce60894e4ab871694d70be0b84","status":"granted","meter":"model_calls","scope":"session","amount":5.0,"approver":"alice","note":"more questions today"}
success | Lagos is the largest city in Nigeria.

The last line is the resumed run’s status and response. Leave out amount to grant the shortfall.

Budgets and the other limits

Budgets are not the only thing that stops a run; they are the only limit in dollars, and the only one across runs.

You want to stop	Use	When it is reached
A run that goes round in circles	`max_steps` (on, 50)	The run ends: `termination_reason` `max_steps`
One run’s model calls or tokens, simply	`request_limit`, `total_tokens_limit` (off)	The run ends: `resource_limit`
Spending, for a run, session, agent or application	Budgets	Before the call; pause for a person, or end

When things go wrong

ValueError: budget meter must be one of …

A meter name that does not exist:

ValueError: budget meter must be one of: model_cost_usd, model_tokens, model_calls, tool_calls, sandbox_seconds, subagent_runs; got 'dollars'

The window and on_exhausted are checked the same way:

ValueError: budget window must be one of: total, day, month; got 'week'
ValueError: budget on_exhausted must be one of: pause, terminate; got 'stop'

ValueError: budgets.application_id is required to budget an application

An application budget needs to know which application it belongs to:

ValueError: budgets.application_id is required to budget an application: it names the deployment or tenant the budget belongs to

Add "application_id": "support-desk" beside the scopes.

Run … is not waiting for a budget decision

grant_budget or deny_budget on a run that is not awaiting_budget — already granted, or never stopped — raises LookupError; over HTTP it is a 404:

{"detail":"Run run_5645e83bbd0f4fa2bb6e92de682abae8 is not waiting for a budget decision (it is completed)"}

A dollar budget never stops a local model

The model has no published price, so model_cost_usd has nothing to count; cost_complete is False in the run’s totals. Budget model_calls and model_tokens instead (above).

The run keeps stopping after every grant

A grant without amount covers only the call that stopped. Grant more headroom: amount=0.50.

Budgets reference

Every meter, window, scope and field.

Approvals

Pausing for a person, for tools as well as money.

Policies

Budgets can live in a policy file, with its rules.

Sandboxes and execution

Where sandbox seconds are spent.

Durable runs

Resume a waiting run from another process, days later.

Security model

What is enforced, and where.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Budgets

Budgets

A run that waits for money

How it works

A charge for work already done never fails the run

Scopes, meters and windows

On a policy object

When a budget runs out

Pause, then grant or deny

End instead of waiting

A model with no published price

Over HTTP

Budgets and the other limits

When things go wrong

Next

Budgets reference

Approvals

Policies

Sandboxes and execution

Durable runs

Security model

​Budgets

​A run that waits for money

​How it works

​A charge for work already done never fails the run

​Scopes, meters and windows

​On a policy object

​When a budget runs out

​Pause, then grant or deny

​End instead of waiting

​A model with no published price

​Over HTTP

​Budgets and the other limits

​When things go wrong

​Next

Budgets reference

Approvals

Policies

Sandboxes and execution

Durable runs

Security model

Budgets

A run that waits for money

How it works

A charge for work already done never fails the run

Scopes, meters and windows

On a policy object

When a budget runs out

Pause, then grant or deny

End instead of waiting

A model with no published price

Over HTTP

Budgets and the other limits

When things go wrong

Next