Gateway Graceful Drain

Let in-flight bot turns finish before the gateway process exits — opt-in with a single timeout setting

When a gateway process receives SIGTERM or SIGINT, it can wait for in-flight bot turns to complete before exiting — instead of cutting them off mid-response. Configure the drain window via the CLI, YAML, or Python.

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

agent = Agent(
    name="SupportBot",
    instructions="Help users with support questions.",
    model="gpt-4o-mini",
)

bots = BotOS(
    agent=agent,
    drain_timeout=30,
)
bots.run()

The user sends SIGTERM to the gateway process; graceful drain stops new work and waits for in-flight bot turns up to drain_timeout.

Quick Start

1. Enable via the CLI flag

   praisonai gateway start gateway.yaml --drain-timeout 30

   The gateway waits up to 30 seconds for in-flight turns to complete before exiting.

2. Enable via YAML config

   # gateway.yaml
   drain_timeout: 30
   
   agent:
     name: assistant
     instructions: "Help users"
     model: gpt-4o-mini
   
   channels:
     telegram:
       platform: telegram
       token: "${TELEGRAM_BOT_TOKEN}"

   praisonai gateway start gateway.yaml

3. Enable via Python

   from praisonaiagents import Agent
   from praisonai.bots.botos import BotOS
   
   agent = Agent(
       name="Bot",
       instructions="Be helpful.",
       model="gpt-4o-mini",
   )
   
   bots = BotOS(agent=agent, drain_timeout=30)
   bots.run()

4. Override drain timeout at stop time

   You can also pass a one-off timeout when stopping programmatically:

   import asyncio
   
   async def main():
       bots = BotOS(agent=agent, drain_timeout=30)
       asyncio.create_task(bots.run_async())
   
       await asyncio.sleep(60)
       await bots.stop(drain_timeout=10)

5. Enable via GatewayConfig (Python-first)

   Set drain_timeout on GatewayConfig directly — no CLI flag and no YAML key required. This closes the CLI + YAML + Python parity gap for embedders wiring up a gateway from Python.

   from praisonaiagents.gateway import GatewayConfig
   
   config = GatewayConfig(drain_timeout=20)
   # feed this config into the gateway/BotOS as usual

   drain_timeout must be >= 0 (ValueError otherwise); 0/None disables the drain window.

6. Bound a wedged teardown with a diagnostic deadline

   stop() also accepts a grace budget — extra seconds beyond drain_timeout before the shutdown-phase deadline watchdog fires a diagnosable self-exit if teardown itself is wedged (adapter disconnect(), WS drain, ledger/DB close). Requires the loop watchdog to be configured; a no-op otherwise.

   await bots.stop(drain_timeout=30, grace=10)
   # → wedged teardown self-exits with an all-thread stack dump at ~40s,
   #   instead of hanging until the supervisor's SIGKILL.

   Full mechanism and YAML config on the Loop Watchdog → Shutdown-phase deadline mode page.

How It Works

The drain phase uses DrainTimeoutPolicy from praisonaiagents.gateway.protocols. If the timeout elapses before all turns finish, the process exits forcefully but still attempts to flush any queued outbound messages.

Behaviour Table

Configuration Precedence

When multiple sources specify drain_timeout, the most specific wins:

The GatewayConfig(drain_timeout=…) field is consulted only when there is no CLI flag and no YAML key. The start_with_config fallback checks "drain_timeout" not in gw_cfg before reading the field, so an explicit drain_timeout: null in YAML wins over the field.

When drain_timeout is 0, the gateway exits immediately on SIGTERM without draining. When drain_timeout is None (and no reliability preset is set), a 5-second drain window is applied by the default posture — use reliability="off" to restore immediate-teardown behaviour.

Best Practices

# kubernetes deployment
terminationGracePeriodSeconds: 60

# gateway.yaml
drain_timeout: 50

Related