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.

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.

Three ways to set it

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

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")

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

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

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".

How It Works

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

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

Best Practices

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.

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

Related