Skip to main content
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.
Liveness closes half-open gateway connections by heartbeating over the wire and reaping any peer that misses too many beats.

​
Quick Start

1

Enable liveness on an agent's gateway

from praisonaiagents import Agent
from praisonaiagents.gateway import GatewayConfig, LivenessConfig
from praisonai_bot.gateway import WebSocketGateway

gateway = WebSocketGateway(
    config=GatewayConfig(liveness=LivenessConfig(enabled=True))
)
gateway.register_agent(Agent(name="Support", instructions="Reply to users"))
2

Tune the cadence

from praisonaiagents.gateway import GatewayConfig, LivenessConfig

config = GatewayConfig(
    liveness=LivenessConfig(
        enabled=True,
        interval_ms=15_000,
        missed_beats_before_reap=3,
    )
)
3

Or configure it in gateway.yaml

gateway:
  liveness:
    enabled: true
    interval_ms: 15000
    missed_beats_before_reap: 3

​
How It Works

The gateway emits a PING on each interval; any inbound frame (a PONG, a peer PING, or a normal message) refreshes last_activity. A silent peer misses beats until the reaper closes it.
PieceOwnerRole
EventType.PING / EventType.PONGProtocolWire frame both peers agree on
LivenessPolicy.evaluate(last_activity, now)Core (pure)Returns KEEP or REAP
Gateway reaper taskWrapper serverEmits PING, calls evaluate, closes with LIVENESS_TIMEOUT
Client watchdogReference clientSends PING, force-reconnects on silence
GatewayCloseCode.LIVENESS_TIMEOUTProtocolTyped close code the client can recognise
A connection is reaped once now > last_activity + interval_seconds × missed_beats_before_reap. Setting enabled=False (the default) makes evaluate always return KEEP, so upgrading changes nothing.

​
Configuration Options

LivenessConfig is the user-facing config; to_policy() bridges it to the pure LivenessPolicy the reaper consumes.

Full field, type, and default reference

​
Common Patterns

Pick a cadence from the peer’s network profile — the default is a no-op until you turn it on.

​
Disabled (default)

from praisonaiagents.gateway import GatewayConfig

config = GatewayConfig()  # liveness disabled, behaviour unchanged

​
Mobile / NAT peers

from praisonaiagents.gateway import GatewayConfig, LivenessConfig

config = GatewayConfig(liveness=LivenessConfig(enabled=True))  # 30s × 2 beats

​
Aggressive reaping for high-turnover realtime

from praisonaiagents.gateway import GatewayConfig, LivenessConfig

config = GatewayConfig(
    liveness=LivenessConfig(enabled=True, interval_ms=5_000, missed_beats_before_reap=2)
)

​
Best Practices

Default is enabled=False — behaviour is unchanged. Only enable it when presence stays online after a peer vanishes.
The server advertises heartbeat_ms; the reference client’s watchdog trips at ~2× that. If you build your own client, honour the advertised value so both sides derive the same window from reap_deadline / interval_seconds.
Treat this close code as expected. Reconnect and resume — don’t surface it as a fatal error to the user.

Reliability Preset

Related resilience knobs

Session Continuity

What survives a reap