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

# Gateway Reliability Preset

> One switch that composes graceful drain + admission control for production gateways

<Note>
  The gateway now ships in the `praisonai-bot` package. `praisonai serve gateway` still works exactly as documented here; for a standalone install see [praisonai-bot Migration](/docs/guides/praisonai-bot-migration).
</Note>

<Note>This page covers the **gateway reliability preset** (drain + admission). For task/workflow retry (retry jitter, `workflow_timeout`, `fail_on_callback_error`), see [Reliability](/docs/features/reliability).</Note>

One parameter composing graceful drain and inbound admission control into a production-ready configuration — without touching individual knobs.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai.bots import BotOS

BotOS(
    agent=Agent(name="SupportBot", instructions="Help users with support questions."),
    platforms=["telegram", "discord"],
    reliability="production",
)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Reliability Preset"
        P[production] --> D1[15s drain]
        P --> A1[CPU-scaled admission]
        P --> Q1[bounded queue 32]
        D[default] --> D2[5s drain]
        O[off] --> D3[0s drain]
    end
    classDef prod fill:#10B981,stroke:#7C90A0,color:#fff
    classDef def fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef off_ fill:#8B0000,stroke:#7C90A0,color:#fff
    class P,D1,A1,Q1 prod
    class D,D2 def
    class O,D3 off_
```

## Quick Start

<Steps>
  <Step title="Python (BotOS)">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonai.bots import BotOS

    BotOS(
        agent=Agent(name="SupportBot", instructions="Help users."),
        platforms=["telegram", "discord"],
        reliability="production",
    ).run()
    ```
  </Step>

  <Step title="Override specific knobs">
    Explicit args always beat the preset — useful for canary deployments:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    BotOS(
        agent=Agent(name="SupportBot", instructions="Help users."),
        platforms=["telegram"],
        reliability="production",
        drain_timeout=30,          # override: 30s instead of preset 15s
    )
    ```
  </Step>

  <Step title="YAML (gateway.yaml)">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    reliability: production
    # or nested under gateway:
    gateway:
      reliability: production
      max_concurrent_runs: 8   # explicit override still respected
    ```
  </Step>

  <Step title="CLI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway start --config gateway.yaml --reliability production
    ```
  </Step>
</Steps>

***

## Profiles

| Profile              | `drain_timeout` | `max_concurrent_runs`                   | `overflow_policy`  | When to use                            |
| -------------------- | --------------- | --------------------------------------- | ------------------ | -------------------------------------- |
| `"production"`       | 15 s            | CPU-scaled: `max(4, min(32, cpus × 4))` | `queue` (depth 32) | Production / staging / rolling deploys |
| `"default"` / `None` | 5 s             | unset (unbounded)                       | `reject`           | Local dev with graceful restart        |
| `"off"`              | 0 s             | unset                                   | `reject`           | Legacy immediate-teardown / unit tests |

<Note>
  `max_concurrent_runs` is calculated as `os.cpu_count() * 4`, clamped to the range \[4, 32]. On a 4-core machine that's 16 concurrent turns; on an 8-core machine, 32. Unknown profile names fail fast with `ValueError`.
</Note>

***

## What Each Knob Does

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant C as Inbound Turn
    participant G as Admission Gate
    participant A as Agent Runner
    participant S as Shutdown

    C->>G: arrives
    G->>G: check concurrent ceiling (production: CPU-scaled)
    alt under ceiling
        G->>A: dispatch immediately
    else at ceiling, queue_depth > 0
        G->>G: wait in bounded queue (max 32)
        G->>A: dispatch when slot opens
    else queue full
        G-->>C: reject (503-equivalent)
    end
    S->>A: drain(15s) — wait for in-flight turns
    A-->>S: turns finish
```

**Graceful drain** — on `BotOS.stop()`, the gateway quiesces ingress and waits for in-flight agent turns to finish before cancelling tasks. The drain window is the maximum time to wait.

**Inbound admission control** — caps the number of concurrent agent runs across all channels. Excess turns either queue (bounded fair wait) or are rejected immediately, depending on the `overflow_policy`.

***

## Precedence Ladder

Explicit constructor fields always win over the preset. Only fields left unset are filled by the preset.

```
CLI flag
  > constructor arg (drain_timeout=, max_concurrent_runs=, admission_policy=)
  > gateway.reliability YAML key
  > top-level reliability: YAML key
  > preset default
```

Example — preset sets drain to 15s, but explicit override wins:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai.bots import BotOS

BotOS(
    agent=Agent(name="SupportBot", instructions="Help users."),
    platforms=["telegram"],
    reliability="production",
    drain_timeout=30.0,  # 30s wins over preset's 15s
)
```

***

## Which Profile Should I Pick?

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q1{Running in production<br/>or staging?}
    Q1 -->|Yes| Prod[reliability=production]
    Q1 -->|No| Q2{Need graceful restarts<br/>in local dev?}
    Q2 -->|Yes| Dev["reliability=default (or None)"]
    Q2 -->|No| Q3{Regression-testing<br/>immediate-teardown behaviour?}
    Q3 -->|Yes| Off[reliability=off]
    Q3 -->|No| Dev

    classDef pick fill:#10B981,stroke:#7C90A0,color:#fff
    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff

    class Prod,Dev,Off pick
    class Q1,Q2,Q3 question
```

***

## What It Does NOT Change

These are already default-on regardless of the reliability preset:

* Durable inbound journal (session level)
* Durable outbound outbox

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start with production and only override what you measure">
    The preset values (15 s drain, CPU × 4 ceiling, 32-deep queue) are conservative defaults tuned for latency-bound LLM workloads. Only override a value after measuring that the default doesn't fit — e.g. a 99th-percentile turn time of 25 s warrants `drain_timeout=30`.
  </Accordion>

  <Accordion title="Use production for rolling deploys">
    `reliability="production"` ensures in-flight conversations finish before a new version takes over. Pair with a process manager that sends `SIGTERM` on deploy.
  </Accordion>

  <Accordion title="Keep default for development">
    `reliability="default"` (or `None`) gives you a 5-second drain so you don't cut conversations mid-turn during `Ctrl+C`, without the admission overhead of production mode.
  </Accordion>

  <Accordion title="Keep off for backward-compat regression testing only">
    `reliability="off"` restores the pre-reliability behaviour (immediate cancel on SIGTERM, unbounded concurrency). Use it only in tests — never deploy `off` to production.
  </Accordion>

  <Accordion title="Override individual knobs when needed">
    If the preset drain window or admission ceiling doesn't fit your load, pass `drain_timeout=` or `max_concurrent_runs=` directly — they always take precedence over the preset. See the [Graceful Drain](/docs/features/gateway-graceful-drain) and [Admission Control](/docs/features/gateway-admission-control) pages for the full knob reference.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway Graceful Drain" icon="hourglass" href="/docs/features/gateway-graceful-drain">
    Drain-only knob — fine-grained drain control without the full preset
  </Card>

  <Card title="Gateway Admission Control" icon="traffic-cone" href="/docs/features/gateway-admission-control">
    Concurrency ceiling and fair queue — the other half of the production preset
  </Card>

  <Card title="Config Reload" icon="arrows-rotate" href="/docs/features/gateway-config-reload">
    Hot-reload gateway.yaml without dropping in-flight turns
  </Card>

  <Card title="Reliability" icon="rotate-ccw" href="/docs/features/reliability">
    Task/workflow retry jitter and failure policies
  </Card>
</CardGroup>