Skip to main content
Flow control bounds per-session inboxes and disconnects slow consumers so a single misbehaving client can’t degrade the whole gateway.

​
Quick Start

1

Defaults work out of the box

Flow control is enabled by default — no configuration needed. Every session gets a 256-message inbox and the gateway disconnects clients whose transport buffer exceeds 1 MB.
from praisonaiagents import Agent, GatewayConfig

agent = Agent(
    name="assistant",
    instructions="You help users with tasks"
)
2

Tune the limits

Adjust thresholds to match your workload.
from praisonaiagents import Agent, GatewayConfig, SessionConfig

config = GatewayConfig(
    max_buffered_bytes=4 * 1024 * 1024,
    session_config=SessionConfig(
        max_inbox=512,
    )
)

agent = Agent(
    name="assistant",
    instructions="You help users with tasks"
)

​
How It Works

Two checks protect the gateway from overload:
Event typeWhen buffer is full
presenceSilently dropped
typingSilently dropped
statusSilently dropped
All other typesConnection closed with code 1013

​
Configuration Options

OptionTypeDefaultDescription
max_inboxint256Maximum queued messages per session. 0 = unlimited. Negative values raise ValueError.
max_buffered_bytesint1048576Maximum buffered bytes before a slow consumer is disconnected. 0 = disable slow-consumer checks. Negative values raise ValueError.
max_inbox is set on SessionConfig; max_buffered_bytes is set on GatewayConfig. 
from praisonaiagents import GatewayConfig, SessionConfig

config = GatewayConfig(
    max_buffered_bytes=1024 * 1024,
    session_config=SessionConfig(
        max_inbox=256,
    )
)
These options are also available in gateway.yaml: 
gateway:
  max_buffered_bytes: 1048576
  session_config:
    max_inbox: 256

​
Client-Side Error Contract

When the inbox is full, the gateway sends this JSON frame before rejecting the message: 
{
  "type": "error",
  "code": "inbox_full",
  "message": "Message queue is full. Please wait for current messages to be processed."
}
When the transport buffer exceeds max_buffered_bytes for a critical event, the gateway closes the WebSocket with:
  • Code: 1013 (Try Again Later)
  • Reason: slow consumer
Clients should reconnect and resume from the last known message.

​
Common Patterns

Chat-heavy workloads — Tighten the inbox to shed load early and fail fast: 
from praisonaiagents import GatewayConfig, SessionConfig

config = GatewayConfig(
    max_buffered_bytes=512 * 1024,
    session_config=SessionConfig(max_inbox=64)
)
Long-running tools — Loosen both limits to avoid spurious disconnections during slow AI responses: 
from praisonaiagents import GatewayConfig, SessionConfig

config = GatewayConfig(
    max_buffered_bytes=8 * 1024 * 1024,
    session_config=SessionConfig(max_inbox=1024)
)
Local development — Disable slow-consumer checks so network hiccups don’t interrupt debugging: 
from praisonaiagents import GatewayConfig, SessionConfig

config = GatewayConfig(
    max_buffered_bytes=0,
    session_config=SessionConfig(max_inbox=0)
)

​
Best Practices

An unlimited inbox (max_inbox=0) lets a slow or malicious client queue messages indefinitely, eventually exhausting gateway memory. Reserve it for local testing only.
A typical chat message is a few kilobytes. Set max_buffered_bytes to at least 10× your largest expected event payload. For file-transfer or streaming use cases, increase to 4–8 MB.
When your client receives {"code": "inbox_full"}, pause new sends and retry with exponential backoff (e.g., 1 s → 2 s → 4 s). Do not flood the gateway with immediate retries.
On receiving WebSocket close code 1013, reconnect after a short delay and replay any messages that were in-flight. The gateway preserves session state during the resume_window (default 24 h), so conversation context is not lost.

Gateway

Full gateway configuration and YAML reference

Gateway Error Handling

Error handling patterns for the gateway