Struct UsageLimits 

pub struct UsageLimits {
    pub max_total_tokens: Option<u64>,
    pub max_cost_usd: Option<f64>,
}

Run-level token / cost budgets applied by the agent loop.

Each limit is independent and optional. A None field imposes no constraint. When a limit is exceeded the run terminates with a BudgetLimitKind identifying which limit fired.

Evaluation boundaries and bounded overshoot

Budgets are evaluated at loop boundaries — before a fresh prompt is ingested, before every LLM turn is dispatched, immediately after context-compaction spend is folded in, and before overflow-recovery summarization — never mid-call. Any single boundary may therefore overshoot by the calls already in flight: one turn call, or up to two compaction summarization calls (the second only when the first summary was truncated and retried with a doubled token budget). All such calls are folded into the cumulative usage and re-checked at the next boundary, so the overshoot is bounded and never compounds.

Three accounting gaps are known and deliberate: a streamed attempt that fails mid-response and is retried may have billed partial tokens the provider error channel does not carry, so those are not counted (tracked alongside the channel’s other gaps); a compaction cancelled between its first (billed) summarization call and a truncation retry drops that first call’s usage (the in-flight future is torn down with the accumulator inside); and a custom compactor installed via with_custom_compactor has its reported usage priced at the run’s provider/model, so cost is approximate when the compactor uses a different backend.

Fields

max_total_tokens: Option<u64>

Maximum cumulative tokens (input + output, summed across every turn) before the run stops.

max_cost_usd: Option<f64>

Maximum estimated cost in USD before the run stops.

Only enforced when the run’s provider/model has pricing metadata in agent_sdk_providers; models without pricing never trip this limit.

Cost tracking follows the loop’s configured provider provenance (the provider/model the top-level provider reports). Behind fallback-provider or model-router wrappers the provenance may name a different backend than the one that actually served a given call, so the estimated cost — and therefore this limit — may be inaccurate there.

Trait Implementations

impl Clone for UsageLimits

fn clone(&self) -> UsageLimits

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UsageLimits

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for UsageLimits

fn default() -> UsageLimits

Returns the “default value” for a type.