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.

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.

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

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.

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.

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