Channel Descriptor

Let a channel plugin declare its config, prompt hint, and setup wizard in one place.

A channel plugin declares — in one place — everything the gateway needs to treat it as first-class: its own config keys, a system-prompt hint, an optional setup wizard, and an optional standalone sender.

Quick Start

1. Declare a descriptor

   List your channel’s config fields and a prompt hint on a small descriptor class:

   from praisonaiagents.bots import ChannelField
   
   class IRCDescriptor:
       config_fields = [
           ChannelField("server", required=True, prompt="IRC server host"),
           ChannelField("nickserv_password", secret=True, env="IRC_NICKSERV_PASSWORD"),
       ]
       system_prompt_hint = (
           "You are replying on IRC: plain text only, one short line."
       )

2. Register the platform

   Pass the descriptor when you register the adapter — the gateway wires config, onboarding, and prompt for you:

   from praisonai.bots._registry import register_platform
   
   register_platform("irc", IRCBot, descriptor=IRCDescriptor())

How It Works

One declaration feeds five consumers when the channel is active.

CLI flags are generated from config_fields

A channel’s declared config_fields are accepted on praisonai bot run as --field-name flags, so the same declaration drives YAML, the wizard, the agent prompt hint, and the CLI.

# IRC plugin declaring `server` and `nickserv_password`
praisonai bot run --platform irc --server irc.libera.chat --nickserv-password $NICK_PW

See praisonai bot run for syntax and the exit-code-2 error on unknown flags.

How the hint reaches the model

The gateway resolves the descriptor’s hint and appends it to the cloned agent’s backstory, then rebuilds system_prompt — the runtime prompt builder reads those, not the construction-only instructions.

from praisonaiagents.bots import ChannelField
from praisonai.bots._registry import register_platform

class IRCDescriptor:
    config_fields = [
        ChannelField("server", required=True, prompt="IRC server host"),
    ]
    # This hint now actually reaches the model on every turn.
    system_prompt_hint = "You are replying on IRC: plain text only, one short line."

register_platform("irc", IRCBot, descriptor=IRCDescriptor())

ChannelField Options

Each ChannelField describes one config key the channel needs.

Interactive Setup

Add an optional setup(io) hook for multi-step flows that a flat field list can’t express — the wizard calls it when present and merges the returned values.

from praisonaiagents.bots import ChannelField
from praisonai.bots._registry import register_platform

class IRCDescriptor:
    config_fields = [
        ChannelField("server", required=True, prompt="IRC server host"),
    ]
    system_prompt_hint = "You are replying on IRC: plain text only, one short line."

    def setup(self, io) -> dict:
        channels = io.prompt("Which channels to join? (comma-separated)")
        return {"channels": [c.strip() for c in channels.split(",") if c.strip()]}

register_platform("irc", IRCBot, descriptor=IRCDescriptor())

Gateway-less scheduled delivery

Declare an optional standalone_sender and your channel also receives scheduled briefs when no gateway is resident, just like the five bundled channels.

class IRCDescriptor:
    config_fields = [
        ChannelField("server", required=True, prompt="IRC server host"),
    ]
    system_prompt_hint = "You are replying on IRC: plain text only, one short line."

    async def standalone_sender(self, target, text):
        await post_to_irc(target.channel_id, text)  # raises on failure

class IRCBot:
    channel_descriptor = IRCDescriptor()  # found by `praisonai schedule tick`
    ...

Best Practices

Related