Skip to main content
Describe your agent, gateway, and channel platforms in a single YAML file — no Python required. 
from praisonaiagents import Agent

agent = Agent(name="bot-agent", instructions="Reply to users across chat channels.")
agent.start("Answer incoming messages from Telegram and Discord.")
The user defines a bot.yaml; the gateway loads it and connects the agent to every configured channel.

​
How It Works

​
Config Structure

​
Quick Start

1

Install

pip install praisonaiagents "praisonai-bot[gateway,bot]"
2

Set credentials

export OPENAI_API_KEY=your_openai_api_key
export TELEGRAM_BOT_TOKEN=your_telegram_token
3

Create bot.yaml

agent:
  name: assistant
  instructions: You are a helpful assistant.
  llm: gpt-4o-mini

gateway:
  host: 127.0.0.1
  port: 8765

platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
4

Start the gateway with your YAML

praisonai-bot gateway start --config bot.yaml
The gateway registers the agent and starts all configured channel bots automatically.

​
Config Options Reference

​
agent section

KeyTypeDefaultDescription
agent.namestrrequiredAgent display name, used as the agent_id for gateway routing
agent.instructionsstrrequiredSystem prompt / instructions for the agent
agent.llmstr"gpt-4o-mini"LLM model identifier (e.g. gpt-4o, gpt-4o-mini)

​
gateway section

KeyTypeDefaultDescription
gateway.hoststr"127.0.0.1"Host to bind the WebSocket server
gateway.portint8765Port to listen on

​
platforms section

Each key under platforms is a platform name. Use ${VAR_NAME} for environment variable interpolation.
Key patternTypeDescription
platforms.<name>.tokenstrBot token for the platform. Supports ${ENV_VAR} substitution
Supported platforms: telegram, discord, slack, whatsapp, and any platform registered via entry points.

​
Environment Variable Interpolation

Values in the form ${VAR_NAME} are resolved from the current environment at startup: 
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}   # reads os.environ["TELEGRAM_BOT_TOKEN"]
  discord:
    token: ${DISCORD_BOT_TOKEN}    # reads os.environ["DISCORD_BOT_TOKEN"]
Tokens stored in ~/.praisonai/.env (written by praisonai-bot onboard) are loaded automatically before interpolation.

​
When to Pick YAML vs Python

ScenarioUse
Operations team manages tokensYAML — credentials stay out of code
Static single-agent setupYAML — fewer moving parts
Dynamic agents (created at runtime)Python — full control over register_agent()
Custom gateway middleware or hooksPython — subclass or extend WebSocketGateway
Multiple environments (dev / staging / prod)YAML — per-environment files with env vars

​
Common Patterns

​
Multi-platform setup

agent:
  name: assistant
  instructions: You are a helpful assistant.
  llm: gpt-4o-mini

gateway:
  host: 0.0.0.0
  port: 8765

platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
  slack:
    token: ${SLACK_BOT_TOKEN}

​
Custom port from environment

gateway:
  host: 0.0.0.0
  port: 9000
Or set the GATEWAY_PORT environment variable — the CLI reads it automatically when --port is not passed.

​
Best Practices

Never hardcode tokens in YAML. Use environment variables and store them in ~/.praisonai/.env (written by praisonai-bot onboard) or your secrets manager.
# Good
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

# Never do this
platforms:
  telegram:
    token: 1234567890:ABCdef...

praisonai-bot gateway doctor --config bot.yaml
This validates every channel token before starting, so a bad token fails fast instead of silently reconnecting.
Keep dev.yaml, staging.yaml, and prod.yaml — each referencing different environment variables. Pass the right one with --config.

Standalone Bot Gateway (Python)

Python API equivalent — register agents programmatically

Gateway CLI

Full list of gateway CLI commands

BotOS

Multi-platform bot orchestration

praisonai-bot SDK

Full bot-tier SDK reference