Budgets

Budgets are set in governance_config["budgets"], one list of limits per scope. Each limit caps one meter over one window.

agent_config = {
    "governance_config": {
        "enabled": True,
        "profile": "interactive-dev",
        "budgets": {
            "application_id": "support-desk",
            "application": [{"meter": "model_cost_usd", "limit": 20.0, "window": "day"}],
            "request": [
                {"meter": "model_cost_usd", "limit": 0.50},
                {"meter": "tool_calls", "limit": 40, "on_exhausted": "terminate"},
            ],
        },
    }
}

Scopes

Scope	Counts
`request`	One run, from `run()` to its end, resumes included. The same limit applies to every run of the agent.
`session`	Every run with the same `session_id`.
`agent`	Every run of this agent.
`application`	Every agent that names the same `application_id` (required for this scope).

Scopes: request, session, agent, application.

Meters

Meter	Counts
`model_cost_usd`	Dollars spent on model calls, priced from the provider’s published rates. Each call’s price is held before it is made.
`model_tokens`	Tokens in and out of model calls.
`model_calls`	Model calls.
`tool_calls`	Tool calls, counted as each is authorized.
`sandbox_seconds`	Seconds sandbox sessions were open.
`subagent_runs`	Workers started with spawn_subagents.

A model call’s price is held before the call: the input it counts, and the output at model_config["max_tokens"], or 4096 tokens (sent to the provider as the call’s ceiling) when none is set.

Windows

Window	Resets
`total`	Never resets: the whole life of the scope (a request, a session…).
`day`	Resets at 00:00 UTC.
`month`	Resets on the first of the month, 00:00 UTC.

A limit

Field	Default
`meter`	required	One of the meters above.
`limit`	required	Greater than zero, in the meter’s unit.
`window`	`"total"`	One of the windows above.
`warn_at`	`0.8`	The fraction of the limit that records a warning in the trace.
`on_exhausted`	`"pause"`	`pause`: the run waits for a person (`awaiting_budget`). `terminate`: the run ends.

What one meter may reach in one scope, and what happens at the wall.

When a budget runs out

A run that would go over a pause limit stops before the call and returns status: "awaiting_budget" with budget_request: the budget, what is spent, what the call needs, and the shortfall. Then:

await agent.grant_budget(run_id, approver=..., amount=...) adds to that budget (without amount, just the shortfall of the call that stopped), recorded with the approver’s name; then await agent.resume(run_id).
await agent.deny_budget(run_id, approver=...) ends the run instead.
await agent.budget_status(run_id) shows each budget’s limit, granted, spent, reserved and remaining.

Over HTTP: GET /runs/{run_id}/budget (the budgets and the run’s requests) and POST /runs/{run_id}/budget. The design is in durable runs.

Get Started

Build

Make It Safe

Run It

See and Improve

How It Works

Reference

HTTP API (OmniServe)

Releases

Budgets

Budgets

Scopes

Meters

Windows

A limit

When a budget runs out

​Budgets

​Scopes

​Meters

​Windows

​A limit

​When a budget runs out

Budgets

Scopes

Meters

Windows

A limit

When a budget runs out