Skip to main content
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).

​
Configuration Options

OptionTypeDefaultDescription
max_budgetfloat | NoneNoneHard 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

Set max_budget on any agent that runs unattended or loops over tools. 0.25–0.25–1.00 is a sensible starting range for research agents.
on_budget_exceeded="warn" lets you see full output while still logging when you’d have been stopped in production.
Budget caps control spend; rate limiters control request frequency. Use both for cost-sensitive deployments.

CLI Budget Handling

Set budgets from the command line

Execution Config

All execution options in one place