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

# Max Tokens

> Control maximum output tokens for agent responses

`--max-tokens` caps the model's output length. When you pass it explicitly, PraisonAI honours it verbatim — even when the value equals the built-in default.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Flag[⌨️ --max-tokens N] --> Sentinel{🔍 typed on<br/>command line?}
    Sentinel -->|yes| Explicit[✅ _max_tokens_explicit=True]
    Explicit --> Wins[🏆 wins over YAML<br/>& per-agent budgets]
    Sentinel -->|no| Default[⚙️ built-in default 16000]

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    classDef cfg fill:#189AB4,stroke:#7C90A0,color:#fff

    class Flag input
    class Sentinel check
    class Explicit,Wins ok
    class Default cfg
```

## Quick Start

<Steps>
  <Step title="Set a budget from your agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(name="Writer", instructions="Write a detailed essay.")
    agent.start("Explain zero-shot prompting in depth.")
    # praisonai "Explain zero-shot prompting in depth." --max-tokens 8000
    ```
  </Step>

  <Step title="Cap output from the CLI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai "Write a detailed essay" --max-tokens 8000
    ```
  </Step>
</Steps>

<Note>
  **Behaviour change (PR [#5360](https://github.com/MervinPraison/PraisonAI/pull/5360) / issue [#5358](https://github.com/MervinPraison/PraisonAI/issues/5358)).** Before this fix, `--max-tokens 16000` was silently dropped because the resolver could not distinguish "user typed 16000" from "argparse filled in the default". The parser now marks explicitness with a sentinel at parse time, so `--max-tokens 16000` behaves identically to `--max-tokens 15999`. Any prior workaround like `--max-tokens 16001` is no longer needed.
</Note>

***

## How It Works

The parser tracks whether you actually typed the flag, so an explicit value always wins — regardless of what it equals.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant You
    participant Parser as CLI Parser
    participant Resolver as Config Resolver
    participant Agent

    You->>Parser: --max-tokens 16000
    Parser->>Parser: sentinel present → _max_tokens_explicit=True
    Parser->>Resolver: max_tokens=16000 (explicit)
    Resolver->>Agent: cap = 16000 (overrides YAML)
    Note over Agent: honoured verbatim
```

### Precedence

The most specific source that you actually set wins.

| Where set | Wins when |
| - | - |
| `--max-tokens N` on the command line (**any** N, including 16000) | You typed the flag. |
| Per-agent `max_tokens:` in YAML | You did **not** type `--max-tokens`. |
| Nested workflow YAML budget | You did not type `--max-tokens` and no per-agent value applies. |
| Built-in default (16000) | Nothing else set it. |

***

## Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "<prompt>" --max-tokens <number> [options]
```

| Option | Description | Default |
| - | - | - |
| `--max-tokens` | Maximum output tokens | 16000 |

***

## Common Patterns

### Short Response

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Summarize in brief" --max-tokens 500
```

### Long-form Content

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Write comprehensive documentation" --max-tokens 32000
```

### With Research

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Deep research on AI" --research --max-tokens 20000
```

***

## Token Limits by Model

| Model | Max Output Tokens |
| - | - |
| gpt-4o | 16,384 |
| gpt-4o-mini | 16,384 |
| claude-3-5-sonnet | 8,192 |
| gemini-2.0-flash | 8,192 |

<Warning>
  Setting max-tokens higher than the model's limit will be capped automatically.
</Warning>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Type the flag when you mean it">
    An explicit `--max-tokens N` always wins — including `--max-tokens 16000`. You no longer need workarounds like `--max-tokens 16001`.
  </Accordion>

  <Accordion title="Let YAML own per-agent budgets">
    Omit `--max-tokens` to let each agent's `max_tokens:` in YAML apply. The CLI default only fills in when nothing else set a budget.
  </Accordion>

  <Accordion title="Stay under the model cap">
    Values above the model's output limit are capped automatically, so match your budget to the model you run.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Max Budget" icon="gauge" href="/docs/features/agent-max-budget">
    Set per-agent token and cost budgets in code.
  </Card>

  <Card title="Model-aware clamp (#4124)" icon="github" href="https://github.com/MervinPraison/PraisonAIDocs/issues/4124">
    Tracking issue for clamping budgets to each model's cap.
  </Card>
</CardGroup>


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