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

# Budget

> Control agent costs with spending limits and usage tracking

Agents can enforce spending limits to prevent runaway costs — set a max budget and the agent stops automatically.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Budget Control"
        A[🤖 Agent] --> U[💰 Usage]
        U --> B{Limit?}
        B -->|OK| C[✅ Continue]
        B -->|Exceeded| S[🛑 Stop]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef usage fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    classDef stop fill:#EF4444,stroke:#7C90A0,color:#fff

    class A agent
    class U,B usage
    class C ok
    class S stop
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
```

## Quick Start

**1. Simple Usage**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant',
  maxCostUsd: 0.50  // Stop after $0.50
});

await agent.chat('Summarize this document');
```

**2. With Configuration**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant',
  maxCostUsd: 1.00
});

const response = await agent.chat('Write a report');
const usage = agent.getUsage();

console.log(`Cost: $${usage.estimatedCostUsd.toFixed(4)}`);
console.log(`Tokens: ${usage.totalTokens}`);
```

**3. With Token Limits**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'Be concise',
  maxTokens: 500,    // Limit output tokens
  maxCostUsd: 0.10   // Also limit cost
});
```

***

## How It Works

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

    User->>Agent: chat("task")
    Agent->>Budget: Check remaining budget
    Budget-->>Agent: OK ($0.30 remaining)
    Agent->>Agent: Generate response
    Agent->>Budget: Record usage
    Budget-->>Agent: Updated ($0.18 remaining)
    Agent-->>User: Response
```

***

## Configuration

| Option | Type | Description |
| - | - | - |
| `maxCostUsd` | `number` | Maximum cost in USD |
| `maxTokens` | `number` | Maximum output tokens |

***

## Common Patterns

### Per-Session Budget

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

// Each session gets $0.25 max
const agent = new Agent({
  instructions: 'You are a research assistant',
  maxCostUsd: 0.25
});

// Agent stops if budget is exceeded mid-task
await agent.chat('Research quantum computing and write a detailed summary');
```

### Monitor and Alert

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant',
  maxCostUsd: 1.00
});

await agent.chat('Write a comprehensive analysis');

const usage = agent.getUsage();
if (usage.estimatedCostUsd > 0.80) {
  console.warn('Budget nearly exhausted:', usage);
}
```

### Batch with Shared Budget

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'Summarize the given text concisely',
  maxTokens: 200,   // Keep each response short
  maxCostUsd: 2.00
});

const documents = ['doc1...', 'doc2...', 'doc3...'];
for (const doc of documents) {
  const summary = await agent.chat(`Summarize: ${doc}`);
  console.log(summary);
}
```

***

## Best Practices

> [accordion] Set limits before production
>
> Always configure `maxCostUsd` before deploying agents to production. Without limits, a runaway loop or unexpectedly large input can result in significant API costs.

> [accordion] Use token limits for predictability
>
> `maxTokens` limits output length, making costs more predictable. Combine with `maxCostUsd` for both per-response and cumulative control.

> [accordion] Monitor usage after each run
>
> Call `agent.getUsage()` after completion to track cumulative spending. Log this data to build cost forecasts over time.

> [accordion] Match budget to task scope
>
> Simple Q\&A tasks need less than $0.01. Detailed research tasks may need $0.10–\$0.50. Set limits to match the expected scope, not just a large safety number.

***

## Related

> [card] [Token Management](https://praison.ai/docs/js/token-management.md)
>
> Control token usage per request

> [card] [Execution](https://praison.ai/docs/js/execution.md)
>
> Execution settings and timeouts


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.