Liveness Policy • AI Agent SDK

LivenessPolicy: Config-driven, pure liveness policy for half-open connection reaping.

LivenessPolicy

Defined in the protocols module.

Config-driven, pure liveness policy for half-open connection reaping.

The default referenced by `gateway.liveness blocks in gateway.yaml and the WebSocketGateway(..., liveness_policy=...) Python surface. It is intentionally minimal and dependency-free so the decision lives in core and is provable in isolation; the wrapper owns the side effects (emit the PING` heartbeat, close the socket, force the client reconnect).

A connection is reaped once its `last_activity is older than interval_ms × missed_beats_before_reap — i.e. it has silently missed that many heartbeat intervals. Any activity (an inbound frame, an inbound PONG, or the peer's own PING) refreshes last_activity and keeps the connection alive. The reference client typically force-reconnects after ~2×` the interval of silence, so it heals before the server reaps it.

The window derivation is shared with the client watchdog via :meth:reap_deadline / :attr:interval_seconds so both sides agree on the same arithmetic from one advertised `interval_ms`.

`interval_ms of 0 disables liveness reaping entirely (today's behaviour: last_activity` is stamped but never acted upon), so the feature is fully backward-compatible and opt-in.

Example::

LivenessPolicy(interval_ms=30_000, missed_beats_before_reap=2)

Properties

Methods

Source