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

   Leave the model unset to resolve it from whichever provider credential is present — no OpenAI key required:

   # bot.yaml — auto-detect provider from whichever API key is set
   agent:
     name: assistant
     instructions: You are a helpful assistant.
     # model omitted ⇒ resolves to the detected provider at load time.
     # Equivalent to:  model: auto
   
   platform: telegram
   token: ${TELEGRAM_BOT_TOKEN}

   Or pin a specific model explicitly — an explicit value always wins:

   agent:
     name: assistant
     instructions: You are a helpful assistant.
     model: 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

Provider auto-detection (model: auto)

Omitting model: and writing model: auto are equivalent — both defer the choice to load time, where the gateway picks a model that matches whichever provider credential is actually present. This is the same detection ladder praisonai setup uses (default_model_for_available_provider), so a bot config is no longer tied to an OpenAI key.

Detection walks the available credentials in this order and returns the first match:

A detected non-OpenAI provider yields a provider-prefixed id (e.g. anthropic/claude-3-5-sonnet-latest). The list above is illustrative — the SDK helper default_model_for_available_provider is the ground truth, so new providers are picked up automatically.

Precedence (highest wins):

An explicit model: on the agent always wins; a default_model on the gateway block wins over detection; model: auto (or an unset model) triggers detection; gpt-4o-mini is used only when nothing else resolves.

gateway section

platforms section

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

Supported platforms: telegram, discord, slack, whatsapp, and any platform registered via entry points.

events — inbound platform events (opt-in)

Add an events: list under a channel to receive reactions, edits, deletions, member changes, and thread creations:

channels:
  my-discord-bot:
    platform: discord
    token: "${DISCORD_BOT_TOKEN}"
    events: [reactions, edits, members, threads]

See Inbound Platform Events for the full list of accepted classes and what each one enables.

Single-platform shorthand

For one platform, declare a top-level platform: (and optionally token:) instead of a platforms: map:

platform: telegram
token: "${TELEGRAM_BOT_TOKEN}"

token: is optional — omit it and the declared platform: resolves the platform’s own documented env var (TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, etc.):

platform: telegram

The declared platform always wins. If other platform credentials are exported in the environment, bot start refuses to auto-enable them and logs a warning:

WARNING Config declares 'platform: telegram'; NOT auto-enabling discord, slack
despite their credentials being present in the environment. The declared
platform wins. To run them too, list them under 'channels:' explicitly.

Admission policy (unknown_user_policy / owner_user_id)

Control who may DM a single-bot instance directly from bot.yaml. Since PR #5111, praisonai bot start wires unknown_user_policy and owner_user_id into the running bot for telegram / discord / slack — matching the gateway path exactly.

# bot.yaml — single-bot admission policy
platform: telegram
token: ${TELEGRAM_BOT_TOKEN}
unknown_user_policy: allow        # deny (default) | pair | allow
owner_user_id: 987654321          # required when unknown_user_policy: pair
agent:
  name: Assistant
  instructions: Reply to incoming messages.

Both fields also work at the channel level for the multi-channel shape:

# bot.yaml — channel-level admission policy
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    unknown_user_policy: pair
    owner_user_id: 987654321
agent:
  name: Assistant
  instructions: Reply to incoming messages.

Values are case-insensitive on load (ALLOW normalises to allow) and whitespace is trimmed. An unquoted numeric owner_user_id (e.g. 987654321) is coerced to a string automatically.

Bot-to-bot inbound (allow_bots / bot_loop_protection)

Wire the bot-to-bot opt-in and the runaway-loop guard directly from bot.yaml — since PR #5242, praisonai bot start reads both allow_bots and bot_loop_protection for telegram / discord / slack and folds them into BotConfig, exactly matching the gateway path.

# bot.yaml
name: Group Helper
platform: telegram
allow_bots: true
bot_loop_protection:
  max_events_per_window: 20
  window_seconds: 60
  cooldown_seconds: 60

Default-off preserves today’s “drop bot-authored inbound messages” behaviour. See Bot Loop Protection for the full policy reference.

Slack single-bot shorthand

Slack Socket Mode also needs an app-level token, so add a top-level app_token: alongside token::

platform: slack
token: "${SLACK_BOT_TOKEN}"
app_token: "${SLACK_APP_TOKEN}"

app_token: accepts the same three forms as token: — plaintext, ${ENV} interpolation, and the { source, id } secret reference.

Run a Slack bot in three lines plus the agent block:

# bot.yaml — Slack Socket Mode single-bot shorthand
platform: slack
token: "${SLACK_BOT_TOKEN}"
app_token: "${SLACK_APP_TOKEN}"

agent:
  name: assistant
  instructions: Reply to Slack mentions.
  llm: gpt-4o-mini

export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...
praisonai bot start --config bot.yaml

Shell execution keys

Add these per-channel keys to let a bot run shell commands with approval routing.

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

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

# Good
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

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

praisonai-bot gateway doctor --config bot.yaml

Related