Gateway Reliability Preset

One switch that composes graceful drain + admission control for the bot gateway

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.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
# Reliability presets configure retries and timeouts around agent.start
agent.start("Retry this if the network blips")

reliability is a single posture switch on BotOS, gateway YAML, or the CLI that maps a profile name onto drain window, concurrency ceiling, and admission queue — without touching individual settings.

The user deploys with a reliability preset; retries, timeouts, and drain behaviour apply automatically.

Quick Start

1. Python — pass reliability= to BotOS

   from praisonaiagents import Agent
   from praisonai.bots import BotOS
   
   agent = Agent(name="assistant", instructions="Help the user.")
   bot = BotOS(agent=agent, platforms=["telegram", "discord"], reliability="production")
   bot.start()
   
2. YAML — set reliability: at the top level

   # gateway.yaml
   reliability: production
   
   agents:
     assistant:
       instructions: "Help the user."
   
   channels:
     telegram:
       token: "${TELEGRAM_TOKEN}"
   

   Run with:

   praisonai gateway start --config gateway.yaml
   
3. CLI flag — override any YAML value

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

   The CLI flag takes the highest precedence and overrides whatever is in the YAML file.

4. Override individual settings after the preset

   Explicit kwargs on BotOS always win over the preset:

   from praisonaiagents import Agent
   from praisonai.bots import BotOS
   
   agent = Agent(name="assistant", instructions="Help the user.")
   
   bot = BotOS(
       agent=agent,
       platforms=["telegram"],
       reliability="production",
       drain_timeout=30.0,   # overrides the preset's 15 s
   )
   bot.start()
   

---

Profiles

Three built-in profiles cover the most common deployment scenarios.

Profile	Drain window	Admission ceiling	Overflow behaviour	Outbound ordering
production	15 s	CPU-scaled max_concurrent_runs	Bounded fair-wait queue (overflow=queue)	strict
default / None (unset)	5 s	none	pass-through	best_effort
off	0 s (immediate teardown)	none	today’s no-backpressure behaviour	best_effort

The production preset enables strict per-conversation FIFO delivery on the outbox — see Outbound Ordering.

---

How It Works

The resolver _reliability.py converts the profile string into concrete values for drain_timeout, max_concurrent_runs, and admission_policy. Those values are passed directly to the underlying WebSocketGateway build step.

Precedence (highest → lowest):

1. Explicit kwargs on BotOS.__init__ — e.g. drain_timeout=30, outbound_ordering="strict"
2. reliability= preset — e.g. "production"
3. SDK defaults

outbound_ordering= is also an explicit kwarg that overrides the preset. Passing outbound_ordering="strict" (or "best_effort") always wins over the profile’s choice; unknown values raise ValueError at resolve time.

---

Configuration Surfaces

Python

from praisonai.bots import BotOS

# Minimal
bot = BotOS(agent=agent, platforms=["telegram"], reliability="production")

# From a YAML config file (reads top-level `reliability:` or `gateway.reliability`)
bot = BotOS.from_config("gateway.yaml")

YAML

Both placements are accepted:

# Top-level
reliability: production

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

CLI

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

---

Common Patterns

Production deployment

from praisonaiagents import Agent
from praisonai.bots import BotOS

agent = Agent(name="support", instructions="Answer customer questions.")
bot = BotOS(
    agent=agent,
    platforms=["telegram", "discord", "slack"],
    reliability="production",
)
bot.start()

Extend the drain window for slow agents

bot = BotOS(
    agent=agent,
    platforms=["telegram"],
    reliability="production",
    drain_timeout=45.0,   # 45s instead of preset 15s
)

Production preset with per-thread ordering

The production preset enables strict ordering; pass a custom lane_key to order sends within a shared channel:

from praisonaiagents import Agent
from praisonai.bots import BotOS

agent = Agent(name="support", instructions="Answer customer questions.")
bot = BotOS(agent=agent, platforms=["slack"], reliability="production")

# Later, when enqueuing on the outbox, group by thread:
await bot.outbox.enqueue(
    idempotency_key=f"reply-{msg_id}",
    target="slack:C0123456",
    payload={"text": reply},
    lane_key=f"slack:C0123456:thread:{thread_ts}",
)

Disable all backpressure for development

reliability: off

---

Best Practices

Use production in all deployed services

production composes drain + admission control together. Enabling them separately is error-prone — the preset guarantees a coherent configuration.

Never mix reliability= with manual drain/admission in YAML unless intentional

Explicit YAML keys like gateway.drain_timeout override the preset. That is correct behaviour when you need to tune a single value, but it can surprise you if you forget the preset was set.

Unknown profile names raise immediately — do not catch the error

An unrecognised profile (e.g. reliability: "fast") raises at startup, not at first request. This fail-fast behaviour is intentional — silent fallback to default would hide misconfiguration.

Use --reliability CLI flag for canary deployments

Deploying a new preset to a single pod via the CLI flag lets you validate behaviour before updating the shared gateway.yaml.

---

Related

Gateway Overview

Bot gateway architecture and core concepts

Gateway Graceful Drain

In-flight turn drain on shutdown or reload

Gateway Admission Control

Cap concurrent runs and queue overflow requests

Gateway Flow Control

Back-pressure and send-policy options

Outbound Ordering

Per-conversation FIFO delivery the production preset turns on