Skip to content

bot-gateway.mdx

Latest commit

 

History

History
296 lines (248 loc) · 7.91 KB

bot-gateway.mdx

File metadata and controls

296 lines (248 loc) · 7.91 KB
Raw
title Bot Gateway
sidebarTitle Gateway Server
description Run multiple bots (Telegram, Discord, Slack) from a single gateway server with multi-agent routing.
icon server 
flowchart LR
    Config[gateway.yaml] --> Gateway[Gateway Server]
    Gateway --> TG[Telegram Bot]
    Gateway --> DC[Discord Bot]
    Gateway --> SL[Slack Bot]
    TG --> AgentA[Agent A]
    DC --> AgentA
    SL --> AgentB[Agent B]
    
    style Config fill:#8B0000,color:#fff
    style Gateway fill:#189AB4,color:#fff
    style TG fill:#189AB4,color:#fff
    style DC fill:#189AB4,color:#fff
    style SL fill:#189AB4,color:#fff
    style AgentA fill:#8B0000,color:#fff
    style AgentB fill:#8B0000,color:#fff
Loading

Run all your bots from one command. The Gateway Server manages multiple bot connections and routes messages to the right AI agent.

Parity with Bot(): praisonai gateway start now applies the same smart defaults as praisonai bot start, resolving the previous "zero tools in daemon mode" issue. Both entry points produce identical behavior with safe tools auto-injected and auto-approval enabled by default.

Quick Start

```bash pip install praisonai ``` Create a `gateway.yaml` file in your project: ```yaml gateway: host: "127.0.0.1" port: 8765 
agents:
  personal:
    instructions: "You are a helpful personal assistant"
    model: gpt-4o-mini
    tools:
      - internet_search
      - get_current_time
    reflection: true
  support:
    instructions: "You are a customer support agent"
    model: gpt-4o
    role: "Customer Support Specialist"
    goal: "Resolve customer issues quickly and accurately"
    backstory: "Expert in troubleshooting and customer care"
    tools:
      - internet_search
    tool_choice: auto
    allow_delegation: false

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    routes:
      dm: personal
      group: support
      default: personal
  discord:
    token: ${DISCORD_BOT_TOKEN}
    routes:
      default: personal
```
```bash export TELEGRAM_BOT_TOKEN=your_telegram_token export DISCORD_BOT_TOKEN=your_discord_token export OPENAI_API_KEY=your_openai_key ``` ```bash praisonai gateway start --config gateway.yaml ``` All bots start together. Messages are routed to the correct agent automatically.

Supported Channels

Full support for DMs, groups, commands, voice, and media. Guild channels, DMs, slash commands, and embeds. Socket Mode, channels, DMs, slash commands, and threads. Cloud API and Web mode. DMs, groups, media support.

Configuration Reference

Gateway Section

Field Type Default Description
host string 127.0.0.1 Address to bind the gateway server
port integer 8765 Port for the WebSocket server

Agents Section

Each agent is defined by a unique ID and its configuration:

agents:
  my_agent_id:
    instructions: "Your system prompt here"
    model: gpt-4o-mini
    memory: true
    tools:
      - internet_search
      - get_current_time
    reflection: true
    role: "Research Analyst"
    goal: "Find accurate information"
    backstory: "Expert researcher"
    tool_choice: auto
    allow_delegation: false
Field Type Default Description
instructions string "" System prompt for the agent
model string None LLM model (e.g., gpt-4o-mini, gpt-4o)
memory boolean false Enable conversation memory
tools list [] Tool names resolved via ToolResolver
reflection boolean true Enable self-reflection / interactive mode
role string None Agent role (CrewAI-style)
goal string None Agent goal (CrewAI-style)
backstory string None Agent backstory (CrewAI-style)
tool_choice string None auto, required, or none
allow_delegation boolean false Allow task delegation to other agents

Channels Section

Each channel maps to a bot platform:

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}    # Environment variable
    routes:
      dm: personal                   # DMs → personal agent
      group: support                 # Groups → support agent
      default: personal              # Fallback agent
Use `${ENV_VAR_NAME}` syntax in token fields. The gateway automatically reads from your environment variables.

CLI Commands

```bash Start Gateway praisonai gateway start --config gateway.yaml ``` 
praisonai gateway start --config gateway.yaml --host 0.0.0.0 --port 9000
praisonai gateway status

Python Usage

```python from praisonai.gateway import WebSocketGateway

Load gateway config, agents, and channels from YAML

gateway = WebSocketGateway.from_config_file("gateway.yaml")

import asyncio asyncio.run(gateway.start())


<Tip>
`from_config_file()` automatically resolves `${ENV_VAR}` syntax in your YAML, creates agents with tools, and configures channel bots.
</Tip>
</Tab>

<Tab title="Programmatic">
```python
import asyncio
from praisonai.gateway import WebSocketGateway
from praisonaiagents import Agent
from praisonaiagents.gateway import GatewayConfig

# Create agents
personal = Agent(name="personal", instructions="You are a helpful assistant")
support = Agent(name="support", instructions="You are a support agent")

# Create gateway
config = GatewayConfig(host="127.0.0.1", port=8765)
gateway = WebSocketGateway(config=config)

# Register agents (use overwrite=False to prevent accidental replacement)
gateway.register_agent(personal, agent_id="personal")
gateway.register_agent(support, agent_id="support", overwrite=False)

# Start gateway
asyncio.run(gateway.start())
```python # After starting the gateway, inspect connected channel bots gateway.list_channel_bots() # ['telegram', 'discord'] gateway.get_channel_bot("telegram") # Returns bot instance gateway.has_channel_bot("slack") # False

Inspect registered agents

gateway.list_agents() # ['personal', 'support'] gateway.get_agent("personal") # Returns Agent instance

</Tab>
</Tabs>

<Accordion title="Advanced: Health Endpoint">
  The gateway exposes a health endpoint at `http://host:port/health`:
  
  ```bash
  curl http://127.0.0.1:8765/health

Returns:

{
  "status": "healthy",
  "uptime": 120.5,
  "agents": 2,
  "sessions": 3,
  "clients": 1,
  "channels": {
    "telegram": {
      "platform": "telegram",
      "running": true
    },
    "discord": {
      "platform": "discord", 
      "running": false
    }
  },
  "push": {
    "enabled": true,
    "push_channels": 2,
    "online_clients": 5,
    "redis_connected": true
  }
}

The push section is only included when push notifications are enabled.

You can still run a single bot without the gateway: 
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

This starts just one bot connected to a single agent — no gateway needed.

Never commit bot tokens to version control. Always use environment variables or a `.env` file.