Gateway Overview

WebSocket gateway for multi-channel agent coordination and communication

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. Zero-config path: just an env var

   Set a platform token and start — no channels: block required:

   export TELEGRAM_BOT_TOKEN=123:abc
   praisonai gateway

   One log line confirms the bot is live:

   Auto-enabled channel 'telegram' from TELEGRAM_BOT_TOKEN

   See Zero-Config Gateway for the full precedence rules and the env-var-to-channel mapping.

3. Custom config path: route, restrict, or use a non-env token

   When you want to route, restrict, or use a non-env token, 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

4. Start the Gateway

   Launch the gateway server. The env-only path needs no --config flag:

   # Zero-config (env var only)
   praisonai gateway
   
   # With a custom config
   praisonai gateway start --config gateway.yaml

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

How It Works

Two inbound surfaces on one listener

The gateway’s single listener hosts two distinct inbound paths:

• /hooks/<path> — the declarative inbound trigger surface: ad-hoc HTTP-to-agent triggers you define with hooks: entries.
• /webhooks/<channel> — signature-verified platform-webhook ingress for mode: webhook channels, each verified fail-closed by its own per-channel verifier.

Leave webhook_port unset on a mode: webhook channel and it serves through /webhooks/<channel> on gateway.port — one URL for every channel. See Shared Webhook Ingress.

Architecture Principles

Single Instance Rule

Critical: Only run one gateway process per state root (~/.praisonai). Two gateways sharing it would:

• Both poll the same Telegram token (causes 409 conflicts)
• Both write the same outbox, DLQ and pairing stores (split-brain state)

The gateway enforces this at startup with a state lock — a second gateway on another port but the same ~/.praisonai is refused. See Single-Instance Enforcement.

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().

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

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

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

channels:
  linear:
    token: ${LINEAR_API_KEY}

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}

Gateway Modes

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

praisonai gateway start --host 127.0.0.1 --port 8765

praisonai gateway start --agents agents.yaml

praisonai gateway start --config gateway.yaml --safe-mode

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
    }
  }
}

Push Transport Health

When push is enabled with Redis fan-out, health() adds a push block reporting the cross-instance transport:

A degraded transport is also listed under degraded_owners as route:redis-pubsub. See Redis Pub/Sub Resilience.

Auth brute-force budgets are also shared across replicas when push.redis is set — see Cluster-Wide Auth Rate Limiting.

Pressure Telemetry

When the back-pressure machinery is wired, health() adds a top-level pressure block that classifies gateway load as nominal, elevated, or saturated — so you see the gateway backing up before it sheds turns:

{
  "status": "healthy",
  "pressure": {
    "admission_in_flight": 15,
    "admission_queued": 40,
    "outbox_pending": 412,
    "outbox_dead_letter": 2,
    "event_loop_lag_p99_ms": 740.0,
    "pressure": "saturated"
  }
}

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

Best Practices

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

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

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

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

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

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

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.

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"].

Related