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.

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.

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:

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

Related