Controlling cost and turns

An agentic loop calls the model repeatedly: each tool call feeds another request back to the LLM until the agent produces a final answer. Left unbounded, a confused or adversarial run can loop indefinitely and burn real money. AgentRoute gives you two hard guardrails on every Agent — max_turns and max_cost — plus a usage object on every result so you can see exactly what a run cost.

This guide covers setting both limits, reading result.usage, and catching the errors raised when a limit is hit.

The two budgets

Both limits are constructor arguments on Agent:

from agentroute import Agent
 
agent = Agent(
    name="researcher",
    model="claude-sonnet-4",
    instructions="Answer the user's question. Use tools when helpful.",
    max_turns=8,        # at most 8 trips through the loop
    max_cost=0.25,      # stop once this run has spent $0.25
)

• max_turns (default 10) bounds the number of iterations of the agentic loop — roughly the number of model calls. Each turn is one LLM request plus any tool calls it triggers. When the count exceeds the limit the run raises ErrorMaxTurns.
• max_cost (default None, meaning no cost cap) bounds the cumulative spend of a single run in USD. When accumulated cost exceeds the limit the run raises ErrorBudget.

A bare name with no max_cost still has the max_turns=10 default, so an agent can never loop forever — but it can still spend more than you intend on a few expensive calls. Set max_cost whenever cost matters.

Reading what a run cost

Every Result carries a Usage object at result.usage. It accumulates across every model call in the run:

result = agent.run("Summarize the latest changes to the pricing page.")
 
print(result.usage.input_tokens)     # prompt tokens sent to the model
print(result.usage.output_tokens)    # completion tokens received
print(result.usage.total_cost_usd)   # cumulative cost of the run, in USD
print(result.usage.model_calls)      # how many LLM requests this run made

Usage has exactly four fields:

model_calls is the practical signal for whether a run is doing more loop iterations than you expected. A single-shot answer is one model call; a run that uses tools will have one call per turn. If model_calls is climbing toward max_turns, the agent is probably struggling — tighten the instructions or the toolset.

Handling a blown budget

When a limit is exceeded, the run does not return a Result — it raises. Both errors subclass ErrorAgent, so you can catch them together or individually. They carry structured fields so you can log, alert, or degrade gracefully.

from agentroute import Agent, ErrorMaxTurns, ErrorBudget
 
agent = Agent(
    name="researcher",
    model="claude-sonnet-4",
    max_turns=8,
    max_cost=0.25,
)
 
try:
    result = agent.run("Find and cross-check three sources on X.")
    print(result)
except ErrorMaxTurns as e:
    print(f"Stopped at turn {e.turn} (limit {e.limit}) — the agent looped too long.")
except ErrorBudget as e:
    print(f"Stopped after spending ${e.spent:.4f} (limit ${e.limit:.4f}).")

The fields on each error mirror the limit that tripped:

If you only need to know that some guardrail tripped — for example to return a fallback response — catch the base class:

from agentroute import ErrorAgent
 
try:
    result = agent.run(prompt)
except ErrorAgent as e:
    # Covers ErrorMaxTurns, ErrorBudget, and any future guardrail.
    log.warning("Agent run halted: %s", e)
    result = None

Choosing sensible limits

There is no universal right number — the budget depends on the model, the tools, and the task. Some guidance that holds up in practice:

Tracking cost across many runs

Because each limit is per-run, enforcing a session- or user-level budget is your job. Sum total_cost_usd as runs complete and stop dispatching new work once you cross your own ceiling:

import asyncio
from agentroute import Agent, ErrorAgent
 
agent = Agent(name="worker", model="claude-sonnet-4", max_turns=6, max_cost=0.10)
 
async def run_with_session_budget(prompts: list[str], session_cap_usd: float) -> None:
    spent = 0.0
    for prompt in prompts:
        if spent >= session_cap_usd:
            print(f"Session cap ${session_cap_usd:.2f} reached — skipping remaining work.")
            break
        try:
            result = await agent.arun(prompt)
        except ErrorAgent as e:
            print(f"Run halted: {e}")
            continue
        spent += result.usage.total_cost_usd
        print(f"{result}  (run cost ${result.usage.total_cost_usd:.4f}, session ${spent:.4f})")
 
asyncio.run(run_with_session_budget(["...", "..."], session_cap_usd=1.00))

The per-run max_cost still protects you against any single run blowing the session budget in one shot; the loop above adds the cumulative ceiling on top.

Related