Gateway Rooms

Run a team of agents in one live Telegram / Slack / Discord chat with a durable, deterministic turn-taking transcript

A gateway room puts a roster of agents into one live chat, where they take bounded, @-addressed turns and reply as a single assistant message.

Quick Start

1. Simplest: Python on one platform

   from praisonai_bot.bots import Bot, GatewayRoom
   from praisonaiagents import Agent
   from praisonaiagents.rooms import RoomConfig
   
   researcher = Agent(name="researcher", instructions="Research the topic.")
   critic = Agent(name="critic", instructions="Critique proposals.")
   
   room = GatewayRoom(
       RoomConfig(name="standup", roster=["researcher", "critic"]),
       {"researcher": researcher, "critic": critic},
   )
   
   Bot("telegram", agent=room).start()

2. With YAML

   Declare the room under rooms: and bind it with a room:<name> route.

   agents:
     researcher:
       instructions: Research the topic.
     critic:
       instructions: Critique proposals.
     writer:
       instructions: Write the final summary.
   
   rooms:
     standup:
       agents: [researcher, critic, writer]
       max_rounds: 3
       max_messages: 20
   
   channels:
     telegram:
       token: ${TELEGRAM_BOT_TOKEN}
       routes:
         group: room:standup

3. Several platforms at once

   from praisonai_bot.bots import BotOS, GatewayRoom
   from praisonaiagents import Agent
   from praisonaiagents.rooms import RoomConfig
   
   researcher = Agent(name="researcher", instructions="Research the topic.")
   critic = Agent(name="critic", instructions="Critique proposals.")
   
   room = GatewayRoom(
       RoomConfig(name="standup", roster=["researcher", "critic"]),
       {"researcher": researcher, "critic": critic},
   )
   
   BotOS(agent=room, platforms=["telegram", "slack"]).start()

User Interaction Flow

1. A user posts a message in a group chat.
2. The gateway resolves the route room:standup and calls GatewayRoom.achat(prompt).
3. Every rostered agent speaks in round 0; later turns go to whoever is @-mentioned.
4. The combined reply (researcher: … then critic: …) returns through the outbox.
5. The group sees one assistant turn.
6. After a restart, the next message resumes the same schedule from the saved transcript.

How a Gateway Room Runs

Configuration Options

Each rooms.<name> YAML entry is one RoomConfig.

Durable Transcript

The transcript lives in GatewayRoom.chat_history, so a restart loses nothing.

• BotSessionManager swaps the transcript in per user/chat and saves it to the configured session store.
• Member replies are stored as {"role": "assistant", "content": "<id>: <text>"}, because session stores keep only role and content.
• Ids containing ": " still reload intact, since the longest id is matched first.
• The session’s per-agent lock keeps one writer per room.

Member Isolation

Each agent is cloned with clone_for_channel() when it joins a room, so history and tools never leak between rooms or routes.

The room swaps each member’s chat_history and tools per turn, so a shared instance would corrupt other routes.

Choosing a Surface

Common Patterns

routes:
  group: room:standup
  dm: support

Best Practices

Related