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.
The fleet breaker sits on top of the per-channel restart budget and trips one aggregate circuit when a systemic fault — a bad shared provider, a network partition, an org-wide expired token — makes every channel restart at once. Instead of a silent fleet-wide reconnect storm, restarts are held and a single operator-facing degraded fact appears with a next step.

​
Quick Start

1

Simple — nothing to change

The breaker is on by default with sensible thresholds. Watch the new fleet block in health output:
breaker_tripped: false with failing_channels: 0 means the fleet is healthy — no action needed.
2

Tune the thresholds

Set any of the three thresholds under gateway.health. Tuning is optional; the defaults trip on a real storm.

​
What “tripped” means

A tripped breaker means the gateway detected a fleet-wide storm and is now holding channel restarts to avoid feeding it — not that a single channel failed. The breaker trips when either aggregate signal crosses its threshold within the trailing hour: the fleet restart rate reaches fleet_restarts_per_hour, or the fraction of failing channels reaches failing_channel_fraction. It stays tripped for breaker_cooldown_s, then re-arms on its own.

​
Agent-centric quick start

Does it protect you out of the box? Yes — the defaults trip on a real storm, and the same doctor already knows what to say.
When the breaker is tripped, the degraded registry carries one gateway / fleet fact. Its retry_hint points straight at the next command:
The fact clears automatically once the storm subsides.

​
Configuration Options

All three thresholds live under gateway.health. Values verified against HealthMonitorConfig (praisonai_bot/gateway/health_monitor.py) and FleetSupervisionPolicy (praisonaiagents/gateway/protocols.py). The fleet block on gateway status health output carries the live state:

​
Common Patterns

Trip earlier on a smaller fleet — lower the fraction so a couple of failing channels are enough:
Hold longer during a known-flaky upstream — extend the cooldown so the breaker does not re-arm into the same storm:

​
Best Practices

40 restarts/hour and 0.5 failing fraction trip on a genuine fleet-wide storm, not on one flaky channel. Change them only if your fleet size or upstream makes the defaults noisy.
breaker_tripped plus failing_channels / total_channels is the single fleet-health signal. You never have to infer “the gateway is thrashing” from individual channel restart counts.
The one degraded-owner fact points at praisonai gateway doctor. Run it to see what tripped rather than restarting channels by hand while the breaker is holding.
After breaker_cooldown_s the breaker clears its event window and re-arms automatically; the degraded fact clears when the storm subsides. Manual intervention is only needed to fix the underlying systemic fault.

Config Migration

One-shot upgrade of an older gateway.yaml with praisonai gateway doctor --fix

Channel Supervision

Per-channel restart budgets and operator pause/resume/reconnect