Gateway Relay Transport

Run bots behind NAT without public webhooks using an out-of-process relay transport

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
# Relay transport carries user messages to the gateway-backed agent
agent.start("Hello via relay")

Relay transport lets a Bot connect to messaging platforms through an outbound WebSocket relay — no public webhook URL required.

The user connects through a relay; messages traverse the relay transport to reach the gateway and agent.

Quick Start

1. Start the relay server

   Run the gateway relay CLI to bridge between the platform and your bot:

   praisonai gateway relay --platform telegram --to wss://gw.internal/relay

2. Connect your bot via relay

   Pass a transport= argument when creating a Bot:

   import os
   from praisonaiagents import Agent
   from praisonai.bots import TelegramBot
   from praisonai.bots.relay import RelayAdapter
   
   agent = Agent(
       name="MyBot",
       instructions="Help users with their questions.",
   )
   
   relay = RelayAdapter(url="wss://gw.internal/relay")
   
   bot = TelegramBot(
       token=os.getenv("TELEGRAM_BOT_TOKEN"),
       agent=agent,
       transport=relay,
   )
   
   bot.run()

3. Scale to zero with go_dormant()

   When idle, call go_dormant() to release the relay connection and stop consuming resources:

   import asyncio
   from praisonaiagents import Agent
   from praisonai.bots import TelegramBot
   from praisonai.bots.relay import RelayAdapter
   
   agent = Agent(name="DormantBot", instructions="Respond to messages.")
   relay = RelayAdapter(url="wss://gw.internal/relay")
   bot = TelegramBot(token=os.getenv("TELEGRAM_BOT_TOKEN"), agent=agent, transport=relay)
   
   async def main():
       await bot.start()
       # After a period of inactivity:
       await bot.go_dormant()
   
   asyncio.run(main())

How It Works

The RelayAdapter maintains a persistent outbound WebSocket connection to the relay gateway. Platform messages arrive through that channel instead of requiring an inbound webhook. Because the connection is outbound-only, the bot runs behind NAT or in a private network with no firewall rules.

When to Use Relay Transport

Configuration

RelayAdapter

Bot(transport=...)

from praisonai.bots.relay import RelayAdapter

relay = RelayAdapter(
    url="wss://gw.internal/relay",
    reconnect_interval=3.0,
)

bot = TelegramBot(token=token, agent=agent, transport=relay)

CLI

praisonai gateway relay --platform <platform> --to <relay-url>

go_dormant()

go_dormant() disconnects the relay transport cleanly when the bot is idle, enabling scale-to-zero hosting. The bot wakes up automatically when a new message arrives and the transport reconnects.

async def on_idle():
    await bot.go_dormant()
    # Bot releases WebSocket connection; reconnects on next inbound

See Gateway Scale-to-Zero for configuring the full idle policy.

Best Practices

Related