Call, tool-call, and elapsed-time limits are checked before every model
round. When one is exhausted, the agent raises a condition of class
llmragent_budget_error without making the next call. max_tokens is a
recorded-use gate: the agent stops before the next call once recorded usage
reaches the limit, but one response can take the total past it because the
response's token count is not known in advance.
Arguments
- max_calls
Maximum number of model calls, counting chat exchanges, memory compactions, and retrieval-memory embedding operations.
- max_tokens
Stop before the next model call once recorded sent and received tokens reach this value.
- max_tool_calls
Maximum executed tool invocations.
- max_seconds
Wall-clock ceiling, measured from the agent's first call.
Details
A call whose usage the provider did not report adds nothing to the recorded
total. Once an agent with a finite max_tokens has made such a call, each
check warns that the limit is compared with recorded tokens only.
save_agent() keeps the counters, so a budget stays binding across
sessions; the elapsed-time limit restarts when the agent is loaded.
Examples
b <- budget(max_calls = 10, max_tokens = 50000)
# A budget with no calls left refuses before any request is sent.
cfg <- LLMR::llm_config("groq", "openai/gpt-oss-20b")
frugal <- agent("Frugal", cfg, budget = budget(max_calls = 0), quiet = TRUE)
tryCatch(frugal$chat("one"),
llmragent_budget_error = function(e) "refused before spending")