Skip to main content
BotOS lets you deploy your AI agent to multiple messaging platforms with just a few lines of code. One agent brain, many channels.

​
Quick Start

from praisonai.bots import Bot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = Bot("telegram", agent=agent)
bot.run()

​
How It Works

1

Create your Agent

Build an Agent, AgentTeam, or AgentFlow — your AI brain.
2

Wrap in a Bot

Bot("telegram", agent=agent) wraps your agent for a single platform.
3

Orchestrate with BotOS

BotOS starts all your bots concurrently — one command, all platforms.

​
Architecture

  • Protocol-driven: BotOSProtocol lives in the lightweight core SDK; heavy implementations live in the wrapper
  • Lazy loading: Platform libraries (telegram, discord, etc.) are only imported when start() is called
  • Agent-centric: Every bot is powered by an Agent, AgentTeam, or AgentFlow
  • Extensible: Register custom platforms at runtime with register_platform()

​
Token Setup

Tokens are resolved automatically from environment variables. Set them once, use everywhere.
PlatformEnvironment Variable
TelegramTELEGRAM_BOT_TOKEN
DiscordDISCORD_BOT_TOKEN
SlackSLACK_BOT_TOKEN + SLACK_APP_TOKEN
WhatsAppWHATSAPP_ACCESS_TOKEN + WHATSAPP_PHONE_NUMBER_ID
You can always override with an explicit token= parameter:
bot = Bot("telegram", agent=agent, token="your-token-here")

​
Usage Examples

​
Single Agent on Telegram

from praisonai.bots import Bot
from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    llm="gpt-4o-mini",
)

bot = Bot("telegram", agent=agent)
bot.run()  # Blocks until Ctrl+C

​
AgentTeam on Discord

from praisonai.bots import Bot
from praisonaiagents import Agent, AgentTeam, Task

researcher = Agent(name="researcher", instructions="Research topics thoroughly")
writer = Agent(name="writer", instructions="Write clear, engaging content")

t1 = Task(name="research", description="Research the user's topic", agent=researcher)
t2 = Task(name="write", description="Write a summary based on research", agent=writer)

team = AgentTeam(agents=[researcher, writer], tasks=[t1, t2])

bot = Bot("discord", agent=team)
bot.run()

​
AgentFlow on Multiple Platforms

from praisonai.bots import BotOS, Bot
from praisonaiagents import Agent, AgentFlow, Task

analyst = Agent(name="analyst", instructions="Analyze data")
reporter = Agent(name="reporter", instructions="Create reports")

t1 = Task(name="analyze", description="Analyze the input", agent=analyst)
t2 = Task(name="report", description="Generate a report", agent=reporter)

flow = AgentFlow(steps=[t1, t2])

botos = BotOS(bots=[
    Bot("telegram", agent=flow),
    Bot("discord", agent=flow),
    Bot("slack", agent=flow, app_token="xapp-..."),
])
botos.run()

​
YAML Configuration

Create a botos.yaml file: 
agent:
  name: assistant
  instructions: You are a helpful assistant.
  llm: gpt-4o-mini
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
Then load and run: 
from praisonai.bots import BotOS

botos = BotOS.from_config("botos.yaml")
botos.run()
Environment variables in ${VAR_NAME} format are automatically resolved.

​
Extending Platforms

Add your own messaging platform in 3 steps:
1

Create your adapter

class LineBot:
    def __init__(self, token="", agent=None, **kwargs):
        self.token = token
        self.agent = agent

    async def start(self):
        # Connect to LINE API and start listening
        ...

    async def stop(self):
        # Graceful shutdown
        ...
2

Register the platform

from praisonai.bots._registry import register_platform

register_platform("line", LineBot)
3

Use it like any built-in platform

from praisonai.bots import Bot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
bot = Bot("line", agent=agent, token="your-line-token")
bot.run()
Your custom adapter class must implement:
MethodRequiredDescription
__init__(**kwargs)YesAccept token, agent, and platform-specific params
async start()YesStart the bot (connect, listen for messages)
async stop()YesGracefully stop the bot
async send_message(channel_id, content)OptionalSend a message programmatically
on_message(handler)OptionalRegister a message handler
on_command(command)OptionalRegister a command handler
is_running (property)OptionalWhether the bot is currently running

​
Managing Bots

from praisonai.bots import BotOS, Bot
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")

botos = BotOS()

# Add bots
botos.add_bot(Bot("telegram", agent=agent))
botos.add_bot(Bot("discord", agent=agent))

# List platforms
print(botos.list_bots())  # ["telegram", "discord"]

# Get a specific bot
tg_bot = botos.get_bot("telegram")

# Remove a bot
botos.remove_bot("discord")

# Start all remaining bots
botos.run()

​
API Reference

​
platform
str
required
Platform name: "telegram", "discord", "slack", "whatsapp", or any registered custom platform.
​
agent
Agent | AgentTeam | AgentFlow
The AI agent that powers the bot.
​
token
str
Explicit token. Falls back to {PLATFORM}_BOT_TOKEN env var.
​
**kwargs
Platform-specific parameters (e.g., app_token for Slack, mode for WhatsApp).
Methods:
  • bot.run() — Start the bot (sync, blocks)
  • await bot.start() — Start the bot (async)
  • await bot.stop() — Stop the bot
  • await bot.send_message(channel_id, content) — Send a message
​
bots
list[Bot]
Pre-built Bot instances to orchestrate.
​
agent
Agent | AgentTeam | AgentFlow
Shared agent — used with platforms to auto-create Bots.
​
platforms
list[str]
Platform names — auto-creates a Bot per platform using agent.
Methods:
  • botos.run() — Start all bots (sync, blocks)
  • await botos.start() — Start all bots (async)
  • await botos.stop() — Stop all bots
  • botos.add_bot(bot) — Register a bot
  • botos.remove_bot("platform") — Remove a bot
  • botos.list_bots() — List platform names
  • botos.get_bot("platform") — Get a bot by platform
  • BotOS.from_config("path.yaml") — Load from YAML
from praisonai.bots._registry import (
    register_platform,    # Add a custom platform
    list_platforms,       # List all platforms
    resolve_adapter,      # Get adapter class by name
    get_platform_registry # Get full registry dict
)