Gateway Overview - PraisonAI

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

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.

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

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. 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
Shutdown forensics — on every exit, one log line and one diagnostic file record why the gateway stopped. See Crash Forensics.

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

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

Gateway Scoped Approvals

Gateway Session Persistence

​Quick Start

​How It Works

​Architecture Principles

​Single Instance Rule

​Channel Isolation

​Live Config Reload

​Fail-Safe Design

​Gateway Modes

​Health Monitoring

​Health Check Limitations

​Configuration Options

​Best Practices

​Cost Optimization

Scale-to-Zero Gateway

​Related

Admission Control

Session Persistence

Windows Deployment

Multi-Channel Telegram

Scale to Zero

Tracing Hook

Quick Start

How It Works

Architecture Principles

Single Instance Rule

Channel Isolation

Live Config Reload

Fail-Safe Design

Gateway Modes

Health Monitoring

Health Check Limitations

Configuration Options

Best Practices

Cost Optimization

Related