Agent Max Budget

Set a USD cap on agent spend via ExecutionConfig

Cap how much an agent can spend per run with ExecutionConfig(max_budget=...) — when the limit is hit, PraisonAI stops the run and raises BudgetExceededError.

Async enforcement. max_budget is now enforced on async paths (astart() / achat()) as well as sync paths. Gateway bots using async agents will receive BudgetExceededError when their configured ceiling is reached. Previously only sync dispatch enforced the limit.

Sync chat parity. The sync OpenAI chat path (agent.chat(), agent.start()) raises BudgetExceededError on a budget trip, matching the async and custom-LLM paths. Older versions could return None instead of raising.

PR #5841: the max_budget pre-call guard now uses the canonical CJK-aware token estimator. Agents that process Chinese, Japanese or Korean text will see the pre-call cost estimate rise toward the real token count; raise max_budget if a previously-passing agent starts hitting the guard.

Provider/model agents are now capped too (PR #6062). Agents built from a provider/model string (anthropic/..., mistral/..., ollama/..., openrouter/...), an llm={...} dict, a base_url, or a model object used to skip max_budget and report total_cost == 0. They now share the same accounting as OpenAI-style models, and the cap is checked on every LLM call — so it can stop a single turn partway through its tool loop.

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="Researcher",
    instructions="You research topics thoroughly",
    execution=ExecutionConfig(max_budget=0.50),
)
agent.start("Summarise today's AI news")

The user sets a spend cap; the agent stops the run and raises BudgetExceededError once estimated cost exceeds the limit.

The top-level Agent(max_budget=...) shortcut was removed (PraisonAI PR #1642). Use execution=ExecutionConfig(max_budget=...) — see CLI budget handling.

​

Three ways to set it

Python, YAML, and the CLI all set the same ExecutionConfig.max_budget.

Python

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="Researcher",
    instructions="You research topics thoroughly",
    execution=ExecutionConfig(max_budget=0.50),
)
agent.start("Summarise today's AI news")

YAML

process: workflow
roles:
  researcher:
    role: Researcher
    goal: Research topics thoroughly
    backstory: You research topics thoroughly
    execution:
      max_budget: 0.50
      on_budget_exceeded: stop
    tasks:
      t1:
        description: Summarise today's AI news
        expected_output: One paragraph

See YAML Reference → execution: block.

CLI

praisonai loop "Summarise today's AI news" --max-budget 0.50

The cap covers the whole loop, not each iteration. Add --on-budget-exceeded warn to log and continue instead of stopping. See CLI Budget Handling.

​

Quick Start

1. Set a simple USD cap

   from praisonaiagents import Agent, ExecutionConfig
   
   agent = Agent(
       name="Researcher",
       instructions="You research topics thoroughly",
       execution=ExecutionConfig(max_budget=0.50),
   )
   
   agent.start("Research the history of AI")
   

   When spend reaches $0.50, the run stops with BudgetExceededError including agent name and totals.

2. Async run with budget cap

   import asyncio
   from praisonaiagents import Agent, ExecutionConfig
   
   agent = Agent(
       name="AsyncResearcher",
       instructions="Research topics asynchronously",
       execution=ExecutionConfig(max_budget=0.50),
   )
   
   async def main():
       try:
           await agent.astart("Research the history of AI")
       except Exception as e:
           if "BudgetExceeded" in type(e).__name__:
               print(f"Budget exceeded: {e}")
   
   asyncio.run(main())
   

   astart() raises BudgetExceededError the same way start() does — the async path now has identical pre-call guards and post-call cost accounting.

3. Warn instead of stopping

   from praisonaiagents import Agent, ExecutionConfig
   
   agent = Agent(
       name="Analyst",
       instructions="Analyse data carefully",
       execution=ExecutionConfig(
           max_budget=1.00,
           on_budget_exceeded="warn",
       ),
   )
   
   agent.start("Summarise this quarterly report")
   

   With on_budget_exceeded="warn", the agent logs a warning but continues. Default is "stop".

max_budget is enforced on both sync (start()) and async (astart()) paths as of 1.6.88+. Gateway bots that call astart() internally now honour the budget cap and raise BudgetExceededError identically to sync runs.

​

How It Works

Every way of building the agent’s LLM is covered:

How the agent’s LLM is set	max_budget enforced	total_cost / cost_summary populated
llm="gpt-4o" and other OpenAI-style names	✅	✅
llm="anthropic/...", mistral/..., ollama/..., openrouter/...	✅	✅
llm={"model": "...", "base_url": "..."}	✅	✅
llm=LLM(...) model object	✅	✅
A turn answered by a fallback_models entry	✅ priced as the model that answered	✅

The cap is checked after each LLM call, including calls inside a tool loop:

from praisonaiagents import Agent, ExecutionConfig

def fetch_price(ticker: str) -> str:
    """Fetch the latest price for a ticker."""
    return f"{ticker}: 123.45"

agent = Agent(
    name="Analyst",
    instructions="Look up prices for the symbols the user names.",
    llm="anthropic/claude-3-5-sonnet-20240620",
    tools=[fetch_price],
    execution=ExecutionConfig(max_budget=0.10),
)

try:
    agent.start("Price AAPL, MSFT, and GOOG.")
except Exception as e:
    print(type(e).__name__, e)  # BudgetExceededError Agent 'Analyst' exceeded budget: ...

Budget tracking adds zero overhead when max_budget is None (the default).

Schedulers use the same brake — see Async Scheduler → Budget-aware Scheduling. Setting max_cost=0 on AsyncAgentScheduler is a real (zero) budget and short-circuits start() (returns False, no background task) when combined with run_immediately=True. As of PraisonAI PR #5766 the sync AgentScheduler matches this behavior on every entry point, including execute_once() (returns None) and start(run_immediately=True).

​

Configuration Options

Option	Type	Default	Description
max_budget	float | None	None	Hard USD limit per agent run. None disables tracking.
on_budget_exceeded	"stop" | "warn" | callable	"stop"	Action when the cap is reached

ExecutionConfig

Full execution configuration reference

CLI Budget Handling

Budget limits from the CLI

​

Best Practices

Start with a conservative cap in production

Set max_budget on any agent that runs unattended or loops over tools. $0.25–$1.00 is a sensible starting range for research agents.

Use warn mode during development

on_budget_exceeded="warn" lets you see full output while still logging when you’d have been stopped in production.

Retrying after the cap sends no request

For a provider/model agent with on_budget_exceeded="stop", once it has crossed max_budget, every later chat() / achat() raises BudgetExceededError again before contacting the provider. Catching the error and retrying cannot spend more — create a new agent (or one with a higher cap) to continue.

Combine with rate limiting

Budget caps control spend; rate limiters control request frequency. Use both for cost-sensitive deployments.

​

See also: Autonomous run budget

ExecutionConfig.max_budget is one of two budget mechanisms. run_autonomous / run_autonomous_async have their own independent cap via AutonomyConfig — pick the one that matches your run type.

Mechanism	Where	On limit hit	Resumable?
ExecutionConfig.max_budget	Any run	Raises BudgetExceededError	No
AutonomyConfig.max_budget_usd / max_tokens	run_autonomous / run_autonomous_async only	Returns AutonomyResult(completion_reason="budget_exhausted")	Yes when budget_action="pause"

For autonomous runs, prefer the AutonomyConfig cap — it pauses recoverably instead of raising. See Autonomy Budget.

​

Related

Autonomy Budget

Spend/token kill-switch for autonomous runs

CLI Budget Handling

Set budgets from the command line

Execution Config

All execution options in one place

Gateway Spend Budget

Cap cumulative per-identity spend across runs on a shared-Agent gateway