CLI Budget Handling

Stop praisonai CLI runs cleanly when an agent hits its budget cap

When a praisonai CLI run goes over its budget, you get a clean error message and exit-code 1 — no Python traceback.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Stay within budget on every LLM call.")
agent.start("Summarise this document.")

The user runs praisonai from the terminal; when the agent exceeds its budget cap, the CLI exits with a clean message instead of a traceback.

​

Quick Start

1. Set a Budget in Your Agent

   from praisonaiagents import Agent, ExecutionConfig
   
   agent = Agent(
       name="Researcher",
       instructions="Research the topic the user asks about",
       execution=ExecutionConfig(max_budget=1.00)  # USD cap
   )
   
   agent.start()  # or run via the praisonai CLI
   
2. Run via CLI

   praisonai "Research the history of AI"
   

   If the run goes over $1.00, the CLI prints (in red):

   Budget limit exceeded: Agent 'Researcher' exceeded budget: $1.0042 >= $1.0000.
   Hint: set budget via execution=ExecutionConfig(max_budget=1.00) on your Agent.
   

   …and exits with code 1.

3. Or set the cap on praisonai loop

   Skip the Python and pass the cap as a flag:

   praisonai loop "Research the topic" --max-budget 0.50
   

   This maps to ExecutionConfig(max_budget=0.50, on_budget_exceeded="stop"), so a budget trip exits with code 1. Add --on-budget-exceeded warn to log and continue instead.

   The cap is cumulative across loop iterations. A --max-budget 1.00 run that spans 20 iterations stops once total spend hits $1.00 — it is **not** $1.00 per iteration.

---

​

How It Works

The praisonai CLI wraps every agent.start(...) / agent.chat(...) call in a budget handler. When the agent raises BudgetExceededError, the CLI:

1. Prints a single-line, red, rich-formatted message including the actionable hint.
2. Exits with code 1 so shell scripts and CI can detect the failure.

• The same handler covers async (agent.astart()) and streaming paths — bots and gateway deployments route through here and respect max_budget identically.

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 here instead of raising.

This works across every CLI display mode: silent (-qq), quiet (-q), verbose (-v), debug (-vv), --output jsonl, --output json, --output flow, --output editor, and default.

---

​

Using the Exit Code in CI / Scripts

if ! praisonai "Research AI trends"; then
    echo "Run failed (likely over budget)"
    exit 1
fi

Exit code reference:

Exit code	Meaning
0	Success
1	BudgetExceededError (or other handled fatal error)

---

​

Why isn’t there a max_budget= shortcut on Agent?

By design. Per AGENTS.md §5.3 (Parameter Consolidation), execution-related knobs live on ExecutionConfig, not as new top-level Agent.__init__ parameters. This keeps the Agent constructor small and discoverable. The CLI’s error message points users to the one correct place to set a budget:

Agent(execution=ExecutionConfig(max_budget=1.00))

There isn’t one on Agent(...). Use execution=ExecutionConfig(max_budget=...) in Python, --max-budget on praisonai loop, or an execution: block in agents.yaml — those are the three supported entry points.

---

​

Catching the error in your own code

If you embed praisonaiagents directly (not via the CLI), you can catch the same exception:

from praisonaiagents import Agent, ExecutionConfig
from praisonaiagents import BudgetExceededError

agent = Agent(
    name="Writer",
    instructions="Write articles",
    execution=ExecutionConfig(max_budget=0.50)
)

try:
    agent.start("Write about climate change")
except BudgetExceededError as e:
    print(f"{e.agent_name} spent ${e.total_cost:.4f} (cap: ${e.max_budget:.4f})")

---

​

Best Practices

Set a budget cap early

Without max_budget, a runaway agent can rack up costs unbounded. Pick a cap based on a few un-budgeted dev runs.

Use the exit code in automation

The graceful exit means CI detects the failure cleanly — no need to grep tracebacks.

Don't look for a top-level max_budget= on Agent

There isn’t one. Use execution=ExecutionConfig(max_budget=...) — that’s the only supported pattern.

---

​

Related

Budget Management

Full SDK API for budgets, cost tracking, and on_budget_exceeded actions

Execution Configuration

All execution settings including retries, timeouts, and rate limits