Gateway Reliability Preset

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

A BotOS(agent=..., ...) or praisonai gateway start with no reliability= argument is now safe by default — the gateway picks a bounded admission ceiling, a fair wait queue, strict outbound ordering, and a drain window sized to the bind (loopback → 5s, real interface → 15s). The reliability= preset is still there for callers who want to override that.

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

agent = Agent(name="assistant", instructions="Help the user.")

# Safe by default: admission ceiling + fair queue + drain, bind-aware.
bot = BotOS(agent=agent, platforms=["telegram", "discord"])
bot.start()

Quick Start

1. Simplest — safe by default

   No reliability= needed. The gateway resolves admission, a fair queue, strict ordering, and a bind-aware drain:

   from praisonaiagents import Agent
   from praisonai_bot.bots.botos import BotOS
   
   agent = Agent(name="assistant", instructions="Help the user.")
   
   # Safe by default: admission ceiling + fair queue + drain, bind-aware.
   bot = BotOS(agent=agent, platforms=["telegram", "discord"])
   bot.start()

2. Force the full production window even on loopback

   bot = BotOS(
       agent=agent,
       platforms=["telegram", "discord"],
       reliability="production",  # 15s drain regardless of bind
   )

3. Explicit opt-out (revert to pre-#3438 immediate teardown)

   bot = BotOS(
       agent=agent,
       platforms=["telegram", "discord"],
       reliability="off",  # no drain, no admission — you asked for it
   )

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

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

6. Override individual settings after the preset

   Explicit kwargs on BotOS always win over the preset:

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

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

The safe posture (unset) and production both enable strict per-conversation FIFO delivery on the outbox — see Outbound Ordering. "default" and "off" keep best_effort for backward compatibility.

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_bot.bots.botos import BotOS

# Minimal — safe by default, no reliability= needed
bot = BotOS(agent=agent, platforms=["telegram"])

# 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

A non-loopback bind auto-selects the full production window — no reliability= argument needed:

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

agent = Agent(name="support", instructions="Answer customer questions.")
bot = BotOS(
    agent=agent,
    platforms=["telegram", "discord", "slack"],
)
bot.start()  # bound to a real interface → 15s drain + admission + fair queue

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

Related