Standalone Bot YAML

Describe a standalone gateway + agent + channels declaratively

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

Key	Type	Default	Description
agent.name	str	required	Agent display name, used as the agent_id for gateway routing
agent.instructions	str	required	System prompt / instructions for the agent
agent.llm	str	"gpt-4o-mini"	LLM model identifier (e.g. gpt-4o, gpt-4o-mini)

gateway section

Key	Type	Default	Description
gateway.host	str	"127.0.0.1"	Host to bind the WebSocket server
gateway.port	int	8765	Port to listen on

platforms section

Each key under platforms is a platform name. Use ${VAR_NAME} for environment variable interpolation.

Key pattern	Type	Description
platforms.<name>.token	str	Bot 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

Scenario	Use
Operations team manages tokens	YAML — credentials stay out of code
Static single-agent setup	YAML — fewer moving parts
Dynamic agents (created at runtime)	Python — full control over register_agent()
Custom gateway middleware or hooks	Python — 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

Always use ${...} for tokens

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...

Run praisonai-bot gateway doctor before going live

praisonai-bot gateway doctor --config bot.yaml

This validates every channel token before starting, so a bad token fails fast instead of silently reconnecting.

Use separate YAML files per environment

Keep dev.yaml, staging.yaml, and prod.yaml — each referencing different environment variables. Pass the right one with --config.

---

Related

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