Configure run-scoped usage limits

UsageLimits() defines run-scoped stop conditions for one call to Agent $run() or $run_sync(). Limits are evaluated against usage added by that run, not the complete persisted conversation. This keeps resumed sessions from inheriting a spent budget.

Request and tool-call limits are checked at model and tool boundaries. Token and cost limits depend on usage reported after a model response, so the run stops after an overage is observed and can exceed a threshold by one response. A NULL field leaves that limit unset on this object; when the object configures or overrides an Agent, Deputy may fill unset fields from the agent's defaults.

Usage

UsageLimits(
  max_requests = NULL,
  max_tool_calls = NULL,
  max_input_tokens = NULL,
  max_output_tokens = NULL,
  max_total_tokens = NULL,
  max_cost_usd = NULL,
  on_exceed = c("stop", "error")
)

Arguments

max_requests

Maximum model requests. NULL leaves the field unset.

max_tool_calls

Maximum requested tool calls. Rejected calls count toward usage. NULL leaves the field unset.

max_input_tokens

Maximum provider-reported input tokens. NULL leaves the field unset.

max_output_tokens

Maximum provider-reported output tokens. NULL leaves the field unset.

max_total_tokens

Maximum input plus output tokens. Cached input is reported separately and is not counted twice. NULL leaves the field unset.

max_cost_usd

Maximum provider-reported estimated cost in US dollars. NULL leaves the field unset.

on_exceed

What to do when a limit is exceeded. "stop" returns an AgentResult with a typed stop reason; "error" emits the final usage event and then signals a structured Deputy limit error.

Value

A UsageLimits object.