Skip to main content
Budget management lets you cap how much an agent spends on LLM calls per run.

​
Quick Start

1

Set a Budget Limit

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="Researcher",
    instructions="You research topics thoroughly",
    execution=ExecutionConfig(max_budget=0.50)  # Stop at $0.50
)

agent.start("Research the history of AI")
2

Check Costs After a Run

from praisonaiagents import Agent

agent = Agent(
    name="Writer",
    instructions="You write articles",
)

agent.start("Write an article about climate change")

# Check how much it cost
print(agent.total_cost)       # e.g. 0.0023
print(agent.cost_summary)     # {'tokens_in': 500, 'tokens_out': 200, 'cost': 0.0023, 'llm_calls': 2}

​
How It Works

After each LLM call, the agent checks the running total against max_budget. If the total exceeds the limit, the agent takes the configured action (stop, warn, or call your handler).

​
What to Choose

​
Budget Actions

When the budget is exceeded, you control what happens:

​
Stop (Default)

Raises BudgetExceededError immediately. 
from praisonaiagents import Agent, ExecutionConfig, BudgetExceededError

agent = Agent(
    name="Researcher",
    instructions="You research topics",
    execution=ExecutionConfig(
        max_budget=0.50,
        on_budget_exceeded="stop",  # Default
    )
)

try:
    agent.start("Research quantum computing")
except BudgetExceededError as e:
    print(f"Agent {e.agent_name} spent ${e.total_cost:.4f} (limit: ${e.max_budget:.4f})")

​
Warn

Logs a warning but continues running. 
agent = Agent(
    name="Researcher",
    instructions="You research topics",
    execution=ExecutionConfig(
        max_budget=1.00,
        on_budget_exceeded="warn",
    )
)

​
Custom Handler

Call your own function when budget is exceeded. 
def my_budget_handler(total_cost, max_budget):
    print(f"Budget alert: ${total_cost:.4f} exceeds ${max_budget:.4f}")
    # Send Slack notification, log to database, etc.

agent = Agent(
    name="Researcher",
    instructions="You research topics",
    execution=ExecutionConfig(
        max_budget=2.00,
        on_budget_exceeded=my_budget_handler,
    )
)

​
Cost Tracking (No Limits)

Every agent tracks costs automatically, even without a budget limit. 
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You help with tasks",
)

agent.start("Summarize this document")

# Always available
print(f"Cost: ${agent.total_cost:.4f}")
print(f"Summary: {agent.cost_summary}")
# {'tokens_in': 350, 'tokens_out': 120, 'cost': 0.0015, 'llm_calls': 1}
PropertyTypeDescription
agent.total_costfloatTotal USD spent so far
agent.cost_summarydictTokens in/out, cost, and LLM call count

​
Configuration Options

Budget is configured through ExecutionConfig: 
from praisonaiagents import ExecutionConfig

config = ExecutionConfig(
    max_budget=0.50,              # USD limit (None = no limit)
    on_budget_exceeded="stop",    # "stop" | "warn" | callable
)
OptionTypeDefaultDescription
max_budgetfloatNoneMax USD per agent run. None = no limit
on_budget_exceededstr or callable"stop"Action when budget exceeded

​
Multi-Agent Budget

Set per-agent budgets in a team: 
from praisonaiagents import Agent, Task, AgentTeam, ExecutionConfig

researcher = Agent(
    name="Researcher",
    instructions="You research topics",
    execution=ExecutionConfig(max_budget=1.00),
)

writer = Agent(
    name="Writer",
    instructions="You write articles",
    execution=ExecutionConfig(max_budget=0.50),
)

task1 = Task(description="Research AI trends", agent=researcher)
task2 = Task(description="Write summary", agent=writer)

team = AgentTeam(agents=[researcher, writer], tasks=[task1, task2])
team.start()

# Check each agent's spending
for agent in [researcher, writer]:
    print(f"{agent.name}: ${agent.total_cost:.4f}")

​
Best Practices

Run a few times without max_budget to understand typical costs. Then set limits based on real data.
Use on_budget_exceeded="warn" while building. Switch to "stop" in production to enforce hard limits.
Give each agent its own budget rather than one shared limit. Research agents typically cost more than formatting agents.
When max_budget is None (default), the budget check is skipped entirely. Cost tracking still runs but adds negligible overhead.

Execution

Iteration limits, timeouts, rate limiting

Guardrails

Safety and validation controls