Gateway Reliability Preset

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

You now get backpressure by default. Leaving reliability unset gives you a bounded admission ceiling, a fair wait queue, strict outbound ordering, and a drain window sized to the bind — no argument required.

from praisonaiagents import Agent
from praisonai_bot.bots.botos import BotOS

# Safe by default: admission ceiling + fair queue + drain, bind-aware.
BotOS(
    agent=Agent(name="SupportBot", instructions="Help users with support questions."),
    platforms=["telegram", "discord"],
)

Quick Start

1. Python (BotOS) — safe by default

   No reliability= argument needed — the gateway resolves a bounded admission ceiling, a fair queue, strict ordering, and a bind-aware drain:

   from praisonaiagents import Agent
   from praisonai_bot.bots.botos import BotOS
   
   BotOS(
       agent=Agent(name="SupportBot", instructions="Help users."),
       platforms=["telegram", "discord"],
   ).run()

2. Override specific knobs

   Explicit args always beat the preset — useful for canary deployments:

   BotOS(
       agent=Agent(name="SupportBot", instructions="Help users."),
       platforms=["telegram"],
       reliability="production",
       drain_timeout=30,          # override: 30s instead of preset 15s
   )

3. YAML (gateway.yaml)

   reliability: production
   # or nested under gateway:
   gateway:
     reliability: production
     max_concurrent_runs: 8   # explicit override still respected

4. CLI

   praisonai gateway start --config gateway.yaml --reliability production

Profiles

Four distinct postures — the unset posture is bind-aware, so it appears twice.

What Each Knob Does

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:

from praisonaiagents import Agent
from praisonai_bot.bots.botos 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?

Most operators pick nothing — the unset posture is safe, and a non-loopback bind auto-selects the full production window.

What Changed on Restart

Before #3442, running the gateway the obvious way gave a no-backpressure deployment that cut in-flight turns on restart. The unset posture now drains gracefully, sized to the bind.

sequenceDiagram
    participant Op as Operator
    participant Gw as Gateway
    participant Ag as In-flight turn

    Note over Op: Before #3442
    Op->>Gw: praisonai gateway start (no reliability flag)
    Gw-->>Op: (no admission, 5s drain)
    Op->>Gw: rolling restart
    Gw-->>Ag: SIGTERM — turn cut mid-response ❌

    Note over Op: After #3442 (safe by default)
    Op->>Gw: praisonai gateway start --host 0.0.0.0
    Gw-->>Op: (admission ceiling + fair queue + 15s drain)
    Op->>Gw: rolling restart
    Gw-->>Ag: SIGTERM — drain window; turn completes ✅

What It Does NOT Change

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

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

Degraded-channel isolation is another default-on opt-out from fail-closed behaviour, independent of the reliability preset: one channel’s unavailable credential isolates just that channel instead of aborting the gateway. See Degraded Channel Isolation.

Cross-instance Redis pub/sub is self-healing: on connection loss the adapter reconnects with bounded backoff and surfaces the outage via route:redis-pubsub in degraded_owners. See Real-Time Push Notifications → HA & cross-instance delivery.

Best Practices

Related