Gateway Overview

WebSocket gateway for multi-channel agent coordination and communication

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.

from praisonaiagents import Agent

agent = Agent(name="gateway-agent", instructions="Route messages through the PraisonAI gateway.")
agent.start("Set up the gateway to handle Telegram and Slack messages.")

The PraisonAI Gateway enables multi-channel agent deployment through a WebSocket server that coordinates communication between agents and various platforms.

The user starts the gateway and sends a message on a channel; the gateway routes it to the right agent and returns the reply.

Quick Start

1. Install Gateway Dependencies

   Install both bot and API dependencies for gateway functionality:

   pip install "praisonai[bot,api]"
   

   The [api] extra provides uvicorn, fastapi, and starlette required by the gateway server.

2. Create Gateway Configuration

   Create a gateway.yaml file:

   gateway:
     host: "127.0.0.1"
     port: 8765
   
   agents:
     assistant:
       model: gpt-4o-mini
       instructions: "You are a helpful assistant."
   
   channels:
     telegram:
       platform: telegram
       token: ${TELEGRAM_BOT_TOKEN}
       routes:
         default: assistant
   
3. Start the Gateway

   Launch the gateway server:

   praisonai gateway start --config gateway.yaml
   

   The gateway starts on port 8765 with WebSocket and HTTP health endpoints.

---

How It Works

Component	Role
Gateway Server	Manages WebSocket connections and routes messages
Channels	Platform-specific integrations (Telegram, Discord, etc.)
Router	Directs messages to appropriate agents based on rules
Agents	Process messages and generate responses
Inbound Triggers	POST /hooks/<path> — start agent runs from external HTTP events (webhooks, CI, IoT). See Inbound Hooks.

---

Architecture Principles

Single Instance Rule

Critical: Only run one gateway process per machine. Multiple processes conflict:

• Both try to bind port 8765
• Both poll the same Telegram token (causes 409 conflicts)
• Session state becomes inconsistent

Channel Isolation

Each channel operates independently:

• Separate token per platform
• Independent routing rules
• Isolated session management
• Per-channel error handling

Live Config Reload

The gateway diffs gateway.yaml against the running config and restarts only affected agents or channels — and for three timing/logging keys, applies the change in place with no restart at all. Invalid YAML saves keep the last-known-good config. The WebSocket server is never restarted. See Gateway Hot-Reload.

Fail-Safe Design

The gateway implements fail-safe patterns:

• Health checks at /health endpoint
• Automatic reconnection for platform polling
• Graceful degradation when agents are unavailable
• Request timeout handling (25-30 seconds for RAG)
• Versioned hello handshake with capability negotiation — see Handshake Protocol. Connecting from Python, the bundled praisonai-bot client performs this handshake automatically and exposes the negotiated client.features / client.policy / client.heartbeat_ms — see Client-side wiring.
• Shutdown forensics — on every exit, one log line and one diagnostic file record why the gateway stopped. See Crash Forensics.
• Opt-in close-the-loop notice on permanent delivery failure — see Undelivered Message Notice.

---

Config Validation

A typo in gateway.yaml won’t start a broken gateway — it fails fast with exit 78 before your users notice.

praisonai gateway start and praisonai bot serve now validate the same gateway.yaml to the same standard: canonical configs start, legacy configs auto-migrate then start, and typos exit 78.

The validator consults the platform registry — built-in platforms plus any published via praisonai.channels / praisonai.bots entry points plus any registered at runtime with register_platform().

Typo channel (telegran) — rejected, exit 78

agents:
  assistant:
    instructions: "You are a helpful assistant."
channels:
  telegran:                     # typo — should be 'telegram'
    token: ${TELEGRAM_BOT_TOKEN}

Before: warns, gateway starts, /health returns 200 — but Telegram is silently dead.

WARNING  Channel 'telegran' platform 'telegran' is not a known platform
         (agentmail, discord, email, slack, telegram, whatsapp)
INFO     Gateway started on http://127.0.0.1:8765

After: rejected before startup, exit 78 — the supervisor does not crash-loop.

ERROR    Gateway config invalid (gateway.yaml):
           - Unknown channel 'telegran' (platform 'telegran').
             Supported platforms: agentmail, discord, email, linear, slack, telegram, whatsapp
$ echo $?                              # 78

Real adapter (linear) — accepted cleanly

channels:
  linear:
    token: ${LINEAR_API_KEY}

Before: spurious “not a known platform” warning, then starts.

After: accepted with no warning — linear is a shipped adapter on the registry.

Plugin channel (mattermost) — accepted via register_platform()

from praisonai.bots._registry import register_platform

class MattermostBot:
    def __init__(self, **kwargs): self.cfg = kwargs
    async def start(self): ...
    async def stop(self): ...

register_platform("mattermost", MattermostBot)

channels:
  mattermost:
    token: ${MATTERMOST_TOKEN}

Before: warned “not a known platform”, gateway started, channel silently dead on the runtime path.

After: accepted on both praisonai bot serve and praisonai gateway start.

See Gateway Exit Codes for how to wire your supervisor so a fatal config error alerts instead of restart-looping.

---

Gateway Modes

Multi-Channel Mode

Run multiple platforms simultaneously:

channels:
  telegram_support:
    platform: telegram
    token: ${TELEGRAM_SUPPORT_TOKEN}
    routes:
      default: support_agent
  
  discord_community:
    platform: discord
    token: ${DISCORD_BOT_TOKEN}
    routes:
      default: community_agent

Each channel requires a unique token and can route to different agents.

WebSocket-Only Mode

Pure WebSocket server without chat platforms:

praisonai gateway start --host 127.0.0.1 --port 8765

Provides WebSocket endpoint for custom client integration.

Agent File Mode

Load agents from separate configuration:

praisonai gateway start --agents agents.yaml

Separates agent definitions from gateway configuration.

---

Health Monitoring

The gateway exposes health information:

curl http://127.0.0.1:8765/health

Response:

{
  "status": "healthy",
  "uptime": 3600.5,
  "agents": 3,
  "sessions": 12,
  "clients": 8,
  "channels": {
    "telegram_support": {
      "platform": "telegram",
      "running": true
    },
    "discord_community": {
      "platform": "discord", 
      "running": true
    }
  }
}

Health Check Limitations

Current implementation limitations:

• "running": true doesn’t guarantee platform polling health
• No detection of Telegram 409 conflicts until PraisonAI fix ships
• Manual verification required for silent bot issues

---

Configuration Options

For complete configuration reference, see the auto-generated SDK documentation. The table below shows common options.

Option	Type	Default	Description
host	str	"127.0.0.1"	Gateway bind address
port	int	8765	Gateway port
max_connections	int	100	WebSocket connection limit
heartbeat_interval	int	30	WebSocket ping interval
session_timeout	int	3600	Session expiration in seconds
session.persist	bool	false	Persist sessions across restarts
session.persist_path	str	~/.praisonai/sessions/	Storage directory
session.store	str	"sqlite"	Transcript backend when persist is on — "sqlite" (SQLite Transcript Store) or "file" (legacy JSON)
session.resume_window	int	86400	Seconds detached sessions stay resumable

---

Best Practices

Edit gateway.yaml live

You can change agent instructions, models, or a single channel section while the gateway runs. Agent-only edits recreate agents without restarting channels. See Hot-Reload.

Use environment variables for secrets

Never hardcode tokens in configuration files:

# Good
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

# Bad  
channels:
  telegram:
    token: "123456:hardcoded_token"

Store tokens in .env file or environment variables.

Implement proper error handling

Monitor gateway logs for platform-specific errors:

# View gateway logs
tail -f ~/.praisonai/logs/gateway.log

# Common error patterns
grep "409\|Conflict\|getUpdates" ~/.praisonai/logs/gateway.log

Configure resource limits

Set appropriate limits based on expected load:

gateway:
  max_connections: 100    # Adjust for concurrent users
  session_timeout: 3600   # 1 hour default
  message_queue_size: 1000

Use unique tokens per channel

Each channel must have its own platform token:

channels:
  telegram_support:
    token: ${TELEGRAM_SUPPORT_TOKEN}  # Bot 1
  telegram_sales:  
    token: ${TELEGRAM_SALES_TOKEN}    # Bot 2 (different bot)

Never reuse tokens across channels.

---

Cost Optimization

Running a PraisonAI gateway on serverless hosts (Fly.io Machines, Modal, Cloud Run) charges for every second the machine is alive — even when no users are chatting. The Scale-to-Zero feature lets the gateway stand transports down after a configurable period of silence and wake back up on the next inbound message, so you pay only for active time.

Scale-to-Zero Gateway

Suspend the gateway when idle and wake on the next message — pay only for active time.

---

Lifecycle

Three opt-in lifecycle policies wire into the primary WebSocketGateway through a lifecycle: block in gateway.yaml, matching CLI flags, and a Python surface. Each is off unless enabled, and configured features surface under health()["lifecycle"].

Scale to Zero

Quiesce when idle for idle_minutes and self-wake on the next message.

Drain Trigger

Epoch-safe external drain marker with a built-in watcher.

Crash-Loop Guard

Halt auto-resume of a channel that keeps crashing on resume.

Event-Loop Watchdog

Detect a wedged asyncio loop and restart before it becomes a zombie.

---

Related

Admission Control

Bound concurrent inbound agent runs with a fair queue and overflow policy

Session Persistence

Survive restarts and resume mid-conversation

Windows Deployment

Complete Windows setup guide

Multi-Channel Telegram

Hermes-style workforce deployment

Scale to Zero

Pay only for active time — idle-dormancy for serverless hosts

Tracing Hook

Emit OpenTelemetry spans across each pipeline stage

Undelivered Notice

Notify users and operators when a reply can’t be delivered