Channel Descriptor • AI Agent SDK

ChannelDescriptor: Optional self-description a channel adapter may expose.

ChannelDescriptor

Defined in the protocols module.

Optional self-description a channel adapter may expose.

A channel plugin declares — in one place, at registration — everything the gateway needs to treat it as first-class:

• `config_fields: its config keys, merged into ChannelConfigSchema` at
• runtime instead of being dropped;
• `system_prompt_hint`: a hint injected whenever that channel is active so
• the agent knows which platform it is replying on and its constraints.

The YAML schema, the onboarding wizard, and the agent prompt all read this single contract. Protocol-only (no heavy imports) so it stays in core; the wrapper subsystems (`_config_schema.py, onboard.py`, prompt assembly) are the consumers.

The two required members above are enough to be first-class: the onboarding wizard derives its prompts directly from `config_fields (both env-backed secrets and plain config keys). A descriptor MAY additionally expose an optional setup(io) hook for bespoke, multi-step flows the field list cannot express; the wizard calls it when present and merges the returned values. It MAY likewise expose an optional standalone_sender — a (sync or async) (target: DeliveryTarget, text: str) -> None that raises on failure — so scheduled deliver: targets reach the channel even when no gateway is resident (praisonai schedule tick from OS cron / CI / scale-to-zero). Because these are optional, a minimal descriptor (like the example below) omits it — so this Protocol is intentionally not used as an isinstance type guard; consumers read attributes with getattr` fallbacks instead.

Example (implementation ships in a `praisonai.channels` plugin)::

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

register_platform(“irc”, IRCBot, descriptor=IRCDescriptor())

Properties

Methods

Source