Channel Descriptor

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, and an optional setup wizard.

Quick Start

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

Availability. Before PraisonAI PR #3622, system_prompt_hint was declared but not delivered to the model on the gateway path — the resolver existed, but nothing called it. As of PR #3622 the gateway auto-injects the hint at per-channel bot construction (and again on hot-reload), so a plugin’s declared hint now actually reaches the agent.

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())

Without a descriptor, a plugin channel’s own keys (like IRC’s server) are silently dropped by the fixed ChannelConfigSchema. The descriptor keeps them.

How It Works

One declaration feeds three consumers when the channel is active.

Consumer	Reads	Effect
Config schema	`config_fields`	Plugin keys validate instead of being dropped
Onboarding wizard	`config_fields` (+ optional `setup`)	Prompts for each field, using `env` as fallback
Agent prompt	`system_prompt_hint`	Appended to the agent’s `backstory` and the rebuilt `system_prompt` at per-channel bot construction

Guarantees. The auto-injection is:

Bounded — a single trailing append.
Idempotent — won’t double-append across hot-reload or re-clone if the hint is already present.
Deterministic — one ordered append keeps the prompt prefix cache-stable.
No-op for built-in channels that declare no hint.
Opt-in — only affects third-party channels that declare a system_prompt_hint.

The hint lands on backstory (and the rebuilt system_prompt) — the fields the runtime prompt builder actually reads — not instructions, which is a construction-only attribute.

Issue #3621: Prior to this release the hint field existed on the descriptor but was never read by the runtime. Third-party channels that shipped a system_prompt_hint before that release should verify their hint now reaches the model.

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.

Field	Type	Default	Description
`name`	`str`	—	Config key name (as it appears under `channels.<platform>`)
`required`	`bool`	`False`	Whether the field must be provided
`secret`	`bool`	`False`	Whether the value is sensitive (masked in prompts/logs)
`prompt`	`str`	`""`	Human-friendly prompt shown by the onboarding wizard
`env`	`Optional[str]`	`None`	Environment-variable name used as a fallback source

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())

setup is optional. A descriptor that only needs declarative config_fields omits it entirely.

Best Practices

Mark secrets with secret=True

Set secret=True on tokens and passwords so the wizard masks them and logs never print the value.

Provide an env fallback for secrets

Add env="IRC_NICKSERV_PASSWORD" so operators can supply credentials via environment variables instead of prompts.

Keep the prompt hint short and concrete

State the platform and its constraints in one line — for example plain text only, one short line — so the agent adapts its replies.

Use setup only when fields aren't enough

Reach for setup(io) for bespoke, multi-step flows. Declarative config_fields cover the common case with no code.

Idempotency & prompt-cache safety

The gateway appends the hint as a single trailing line, so injection is deterministic and the prompt prefix stays cache-stable across turns. A hint already present on the agent’s backstory is a no-op on hot-reload, so re-clones never duplicate it.

Messaging Bots

Connect agents to Telegram, Slack, Discord, and more

Bot Platform Capabilities

How platform capabilities drive channel behaviour

Gateway

Multi-agent coordination across channels

Plugins

Ship channels and tools as pip packages

Channel Directory

How an adapter enumerates the channels it can see

Visible-Outcome Guarantee

Every inbound turn ends in a visible reply or a deliberate silence

Prompt-hint auto-injection introduced in PraisonAI PR #3622 (fixes #3621).

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Channel Descriptor

Quick Start

How It Works

How the hint reaches the model

ChannelField Options

Interactive Setup

Best Practices

Messaging Bots

Bot Platform Capabilities

Gateway

Plugins

Channel Directory

Visible-Outcome Guarantee

​Quick Start

​How It Works

​How the hint reaches the model

​ChannelField Options

​Interactive Setup

​Best Practices

​Related

Messaging Bots

Bot Platform Capabilities

Gateway

Plugins

Channel Directory

Visible-Outcome Guarantee

Quick Start

How It Works

How the hint reaches the model

ChannelField Options

Interactive Setup

Best Practices

Related