> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

<Note>
  **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.
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[User Prompt] --> A[Agent Run]
    A --> T[Track Token Cost]
    T --> C{Under Budget?}
    C -->|Yes| R[Continue]
    C -->|No| X[BudgetExceededError]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class A agent
    class U,T,C,R,X tool
```

<Warning>
  The top-level `Agent(max_budget=...)` shortcut was **removed** (PraisonAI PR #1642). Use `execution=ExecutionConfig(max_budget=...)` — see [CLI budget handling](/docs/features/cli-budget-handling).
</Warning>

## Quick Start

<Steps>
  <Step title="Set a simple USD cap">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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.
  </Step>

  <Step title="Async run with budget cap">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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.
  </Step>

  <Step title="Warn instead of stopping">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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"`.
  </Step>
</Steps>

<Note>
  `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.
</Note>

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Budget

    User->>Agent: start(prompt)
    loop Each LLM call
        Agent->>LLM: chat completion
        LLM-->>Agent: response + usage
        Agent->>Budget: record actual cost
        alt stop mode AND total >= max_budget
            Agent-->>User: BudgetExceededError
        else warn/callable AND total >= max_budget
            Budget-->>Agent: trigger warn / handler
        end
    end
    Agent-->>User: result
```

Budget tracking adds zero overhead when `max_budget` is `None` (the default).

## Configuration Options

| Option               | Type                           | Default  | Description                                             |
| -------------------- | ------------------------------ | -------- | ------------------------------------------------------- |
| `max_budget`         | `float \| None`                | `None`   | Hard USD limit per agent run. `None` disables tracking. |
| `on_budget_exceeded` | `"stop" \| "warn" \| callable` | `"stop"` | Action when the cap is reached                          |

<CardGroup cols={2}>
  <Card title="ExecutionConfig" icon="code" href="/docs/sdk/reference/praisonaiagents/classes/ExecutionConfig">
    Full execution configuration reference
  </Card>

  <Card title="CLI Budget Handling" icon="terminal" href="/docs/features/cli-budget-handling">
    Budget limits from the CLI
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Start with a conservative cap in production">
    Set `max_budget` on any agent that runs unattended or loops over tools. $0.25–$1.00 is a sensible starting range for research agents.
  </Accordion>

  <Accordion title="Use warn mode during development">
    `on_budget_exceeded="warn"` lets you see full output while still logging when you'd have been stopped in production.
  </Accordion>

  <Accordion title="Combine with rate limiting">
    Budget caps control spend; rate limiters control request frequency. Use both for cost-sensitive deployments.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="CLI Budget Handling" icon="wallet" href="/docs/features/cli-budget-handling">
    Set budgets from the command line
  </Card>

  <Card title="Execution Config" icon="settings" href="/docs/features/agent-centric-api">
    All execution options in one place
  </Card>
</CardGroup>