Bot Streaming Replies

Show live draft replies on Telegram/Discord/Slack as your agent thinks

Channel bots can post a quick placeholder message and progressively edit it in place as the agent’s answer streams in — replacing the old “stare at a typing indicator for 45s, then a wall of text lands in one burst” experience.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
agent.start("Explain quantum computing in simple terms.")

The user waits on Telegram, Discord, or Slack; a placeholder message updates in place as the agent streams its answer.

Quick Start

1. Enable with one flag (CLI)

   praisonai bot telegram --token $TELEGRAM_BOT_TOKEN --stream

2. Enable in YAML

   channels:
     telegram:
       token: ${TELEGRAM_BOT_TOKEN}
       streaming: true
       stream_edit_interval_ms: 700
     discord:
       token: ${DISCORD_BOT_TOKEN}
       streaming: true
       stream_edit_interval_ms: 700
     slack:
       token: ${SLACK_BOT_TOKEN}
       app_token: ${SLACK_APP_TOKEN}
       streaming: true
       stream_edit_interval_ms: 700

3. Enable in Python

   The API is identical across all three bots — create an Agent, then pass it to the bot with streaming=True.

   Telegram

   from praisonaiagents import Agent, BotConfig
   from praisonai.bots import TelegramBot
   
   agent = Agent(name="assistant", instructions="Be helpful and concise.")
   
   bot = TelegramBot(
       token="...",
       agent=agent,
       config=BotConfig(
           token="...",
           streaming=True,
           stream_edit_interval_ms=700,
       ),
   )
   bot.start()

   Discord

   from praisonaiagents import Agent, BotConfig
   from praisonai.bots import DiscordBot
   
   agent = Agent(name="assistant", instructions="Be helpful and concise.")
   
   bot = DiscordBot(
       token="...",
       agent=agent,
       config=BotConfig(
           token="...",
           streaming=True,
           stream_edit_interval_ms=700,
       ),
   )
   bot.start()

   Slack

   from praisonaiagents import Agent, BotConfig
   from praisonai.bots import SlackBot
   
   agent = Agent(name="assistant", instructions="Be helpful and concise.")
   
   bot = SlackBot(
       token="...",
       agent=agent,
       config=BotConfig(
           token="...",
           streaming=True,
           stream_edit_interval_ms=700,
       ),
   )
   bot.start()

How It Works

Works with recipe/YAML-backed agents too

Recipe-backed bots (praisonai serve recipe … or a channel whose capabilities name a recipe:) stream identically to Python-Agent-backed ones — DraftStreamer edits, status phrases, and SSE chunks all apply.

praisonai serve recipe my_recipe --stream

Bind a channel to a recipe and streaming is on with no extra flag:

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    capabilities:
      recipe: my_recipe

Turning on streaming at the gateway is enough — the recipe surface participates automatically. See Recipe Serve for the async surface and the recipe-event mapping.

Configuration Options

Per-channel streaming support

See Channel Capabilities for the full matrix including reactions and typing.

Advanced configuration (StreamingConfig)

For progress mode, custom placeholder text, or fine-grained min_delta control, use the lower-level StreamingConfig API.

Streaming Modes

Four modes are available to match different use cases:

Auto mode

auto picks the right mode per channel: it streams (draft) where the channel can edit and falls back to off where it can’t — one config, no per-channel branching.

The same StreamingConfig runs on both an editable and a non-editable channel. Telegram streams live; WhatsApp delivers a single final message.

from praisonaiagents import Agent, BotConfig
from praisonai.bots import TelegramBot, WhatsAppBot, StreamingConfig, StreamingMode

agent = Agent(name="assistant", instructions="Be helpful and concise.")

# Same StreamingConfig works on both channels — Telegram streams live,
# WhatsApp delivers a single final message. No per-channel branching.
cfg = StreamingConfig(mode=StreamingMode.AUTO, min_interval=1.0)

telegram = TelegramBot(token="...", agent=agent, config=BotConfig(token="..."))
telegram.configure_streaming(cfg)

whatsapp = WhatsAppBot(token="...", agent=agent, config=BotConfig(token="..."))
whatsapp.configure_streaming(cfg)

The same YAML block drops onto every channel — each resolves on its own capabilities:

channels:
  telegram:                 # live_edit=True → resolves to draft
    token: ${TELEGRAM_BOT_TOKEN}
    streaming:
      mode: auto
      min_interval: 1.0
  whatsapp:                 # live_edit=False → resolves to off
    token: ${WHATSAPP_BOT_TOKEN}
    streaming:
      mode: auto
      min_interval: 1.0

On Telegram the user sees a placeholder that edits in place; on WhatsApp the same agent replies with one final message. Tail the bot log to confirm: INFO ... 'auto' resolved to 'draft' for Telegram, WARNING ... 'auto' resolved to 'off' for WhatsApp.

At init time, auto resolves against the channel’s can_edit capability and logs the outcome:

Edit-less channels with status text

A channel that can’t edit or react can still show progress if its adapter sets supports_status_text=True and implements set_status_text. The activity line then goes to that status line instead of being dropped.

• Only auto and progress are routed to the status line. draft still falls back to off on channels that can’t edit.
• If a status line hasn’t changed, it isn’t sent again, so there is no extra API cost. finalize() sends the answer, then clears the line with an empty string.
• No built-in adapter turns this on yet. See Textual Status Line to add it to a custom adapter.

StreamingConfig options

Per-bot configure_streaming

configure_streaming has the same shape on every bot — pass a StreamingConfig and the override sticks.

from praisonai.bots import TelegramBot, StreamingConfig, StreamingMode

bot = TelegramBot(token="...", agent=agent)
bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.DRAFT,
    min_interval=1.0,
    min_delta=120,
))

from praisonai.bots import DiscordBot, StreamingConfig, StreamingMode

bot = DiscordBot(token="...", agent=agent)
bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.DRAFT,
    min_interval=2.0,          # Discord — stricter edit rate limits
    min_delta=120,
))

from praisonai.bots import SlackBot, StreamingConfig, StreamingMode

bot = SlackBot(token="...", agent=agent)
bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.DRAFT,
    min_interval=1.0,          # Slack chat.update is more generous
    min_delta=120,
))

Long streamed replies auto-chunk (every channel)

Every platform caps message length (Telegram 4096 UTF-16 units, Discord 2000 characters). A streamed answer above the cap can’t be delivered by editing a single placeholder, so the shared DraftStreamer splits it automatically — the same way on Telegram, Discord, Slack, and any future adapter.

When the final answer, measured in the adapter’s length_unit, exceeds the channel’s text_limit, finalize():

1. splits it with chunk_message + enforce_hard_cap (paragraph → newline → sentence boundaries),
2. edits the placeholder with chunk 1 (falling back to a fresh send_message if the edit fails), and
3. sends chunks 2..N as follow-on messages through adapter.send_message.

The user sees one coherent reply split across multiple messages, not a truncated or dropped answer. No config needed — this is on whenever streaming is enabled.

Follow-on chunks are not wrapped in deliver_with_retry — the adapter’s send_message already retries and parks exhausted sends in the DLQ, so wrapping again would re-send a parked chunk and duplicate it. A failing follow-on chunk is logged and the remaining chunks still ship.

Slack: threaded replies skip streaming (by design)

Slack’s shared DraftStreamer posts and edits a placeholder at the channel root, so a reply that must land in a thread bypasses streaming — streaming at the root would strand the answer in the main channel.

For a reply destined for a thread — either the inbound message was itself in a thread (thread_ts is set) or the bot is configured with reply_in_thread: true — the adapter falls back to the existing thread-aware single-message send path (_send_response_with_media), which honours thread_ts and uploads any MEDIA: attachments correctly. A threaded answer is never stranded in the main channel.

Slack: MEDIA: directives still upload audio

A MEDIA:/path/to/reply.mp3 directive still works in streamed Slack replies — the text is edited into the placeholder and the audio is uploaded afterwards.

The final content is parsed via split_media_from_output(...), the text portion is edited into the placeholder, and any audio files are uploaded via files_upload_v2(channel=..., file=...). The directive line itself is never written literally into the chat.

Progress feed style

Set progress_style: feed to render tool calls as a bounded rolling multi-line status view instead of a single overwritten label.

A research agent on Telegram chains web_search, fetch_url, and summarize. With the default progress_style="line", each tool overwrites the last, so a failed fetch_url vanishes. With feed, every step keeps its own line and outcome glyph:

from praisonaiagents import Agent
from praisonai.bots import TelegramBot, StreamingConfig, StreamingMode
from praisonaiagents import BotConfig

agent = Agent(
    name="research-assistant",
    instructions="Research the user's question with web tools and summarise.",
    tools=[web_search, fetch_url, summarize],
)

bot = TelegramBot(
    token="...",
    agent=agent,
    config=BotConfig(token="...", streaming=True),
)
bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.PROGRESS,
    progress_style="feed",     # enable the multi-line rolling feed
    progress_max_lines=6,      # keep it short on mobile
    progress_max_line_chars=100,
))
bot.start()

The user’s Telegram message updates in place with a live per-step audit trail:

✓ web_search — 5 results
✗ fetch_url — timeout
⏳ summarize

Each tool gets its own line with a state glyph — ⏳ running, ✓ done, ✗ error — instead of one label that overwrites itself.

When to use which style

How one tool flows through the feed

A tool’s start event and its matching finish event share one correlation id, so the line updates in place instead of duplicating.

Privacy-safe activity surface

During a long, output-silent tool run in progress mode, show a curated phrase like “Searching the web…” instead of the raw tool name (Running web_fetch...) — tool names, args, command strings, URLs and file paths are never surfaced.

Quick Start

1. Enable in YAML

   channels:
     telegram:
       token: ${TELEGRAM_BOT_TOKEN}
       streaming:
         mode: progress
         activity_status:
           enabled: true
           phrases:
             web:     "Searching the web…"
             search:  "Looking that up…"
             shell:   "Running a command…"
             code:    "Writing and running code…"
             file:    "Reading files…"
             mcp:     "Talking to a tool…"
             default: "Working on it…"

   enabled: false disables the surface (yields activity_phrases=None). An inline activity_phrases: {...} shorthand is also accepted in place of the activity_status block.

2. Enable in Python

   from praisonaiagents import Agent, BotConfig
   from praisonai.bots import TelegramBot, StreamingConfig, StreamingMode
   
   agent = Agent(name="assistant", instructions="Be helpful and concise.")
   
   bot = TelegramBot(token="...", agent=agent, config=BotConfig(token="..."))
   bot.configure_streaming(StreamingConfig(
       mode=StreamingMode.PROGRESS,
       activity_phrases={
           "web":     "Searching the web…",
           "shell":   "Running a command…",
           "default": "Working on it…",
       },
   ))
   bot.start()

Category → phrase mapping

Each tool name is lowercased and matched by substring against these hints — the first match wins, and anything unmatched falls to default.

resolve_activity_category(None) and resolve_activity_category("") both return "default".

What the user sees

A tool named web_fetch_secret_url maps to web, so the user only ever sees the curated phrase — never the tool name.

Interaction flow

The tool name never reaches the chat surface when a catalogue is configured — the phrase is chosen from the category alone.

Which progress rendering to choose

Three renderings live on this page — pick per channel.

Precedence with progress_style: feed

When activity_phrases is set, the raw feed is not rendered — showing it would fold tool names/summaries into the output and bypass the privacy guarantee. The curated single-line phrase is shown instead. Opting into the catalogue therefore disables the multi-line feed on that channel; choose one per channel.

Partial-catalogue safety

If a phrase for the matched category is missing and no default is configured, the surface falls back to the safe generic line Working on it… — never the raw tool name. A catalogue with only {"web": "Searching the web…"} shows Working on it… for a shell tool, not Running bash....

Best practices

streaming:
  mode: progress
  activity_status:
    enabled: true
    phrases:
      web:     "Searching the web…"
      default: "Working on it…"   # covers everything else

Flood-control

Your Telegram bot is streaming a long answer during peak hours. Telegram starts returning 429 after the third edit. The streamer doubles its edit interval (1.5s → 3s → 6s → capped at max_interval). After disable_progressive_edits_after consecutive failures it stops editing entirely and waits — when finalize() fires it delivers the completed answer as a fresh message. The user never sees a stuck placeholder, never sees a partial reply, and the rest of your bot’s chats are unaffected because the backoff is per-stream.

Reasoning-tag filtering

Default ON. <think> and <reasoning> spans (case-insensitive, multi-line) are stripped from both streamed and final output. A trailing unclosed opening tag is also dropped so internal reasoning never leaks mid-stream while a block is still being produced. Set strip_reasoning_tags: false to opt out (for example, on a reasoning-transparency bot).

from praisonai.bots._streaming import strip_reasoning_tags

strip_reasoning_tags("Hi <think>secret</think> there")        # -> "Hi  there"
strip_reasoning_tags("a <REASONING>x\ny</REASONING> b")       # -> "a  b"
strip_reasoning_tags("Answer <think>still going")             # -> "Answer "

YAML vs Python vs CLI

YAML Configuration

Add to your bot.yaml under the channel configuration:

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    streaming:
      mode: progress                # off | draft | progress | auto (see Auto mode)
      progress_style: feed          # "line" (default) or "feed"
      progress_max_lines: 8
      progress_max_line_chars: 120
      min_interval: 1.5
      min_delta: 120
      placeholder_text: "🤔 Thinking..."
      progress_prefix: "🤔 "
      # New in #2356
      disable_progressive_edits_after: 3
      flood_backoff_factor: 2.0
      max_interval: 30.0
      strip_reasoning_tags: true
      # Privacy-safe activity surface (opt-in). Draws the progress line
      # exclusively from these phrases; tool names/args/URLs never leak.
      activity_status:
        enabled: true
        phrases:
          web:     "Searching the web…"
          search:  "Looking that up…"
          shell:   "Running a command…"
          code:    "Writing and running code…"
          file:    "Reading files…"
          mcp:     "Talking to a tool…"
          default: "Working on it…"

Python API

Configure streaming programmatically with the configure_streaming() method:

from praisonai.bots import TelegramBot, StreamingConfig, StreamingMode

bot = TelegramBot(token="...", agent=agent)

# Enable with defaults
bot.configure_streaming(StreamingConfig(mode=StreamingMode.DRAFT))

# Custom configuration
bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.PROGRESS,
    min_interval=2.0,
    min_delta=200,
    placeholder_text="Working...",
    progress_prefix="⚡ "
))

# Multi-line feed style (per-step ⏳/✓/✗ glyphs)
bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.PROGRESS,
    progress_style="feed",
    progress_max_lines=6,
    progress_max_line_chars=100,
))

Manual Streamer Usage

For advanced use cases, you can use DraftStreamer directly:

from praisonai.bots import DraftStreamer, StreamingConfig, StreamingMode

streamer = DraftStreamer(
    adapter=bot_adapter,              # implements BotAdapter Protocol
    channel_id="123456",
    config=StreamingConfig(mode=StreamingMode.DRAFT, min_interval=1.5),
    rate_limiter=None,                # optional, defaults from platform
    platform="telegram",              # enables platform-specific recoverable-error classification
)

message_id = await streamer.start()                      # sends placeholder
# ... agent run subscribes streamer.on_event through agent.stream_emitter.add_callback(...) ...
await streamer.finalize(final_response_text)             # final edit with full text

Best Practices

# Telegram (liberal editing)
streaming:
  mode: draft
  min_interval: 1.0

# Discord (stricter limits)
streaming:
  mode: draft
  min_interval: 2.0

# Good for agents that use many tools
bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.PROGRESS,
    progress_prefix="🔧 "
))

bot.configure_streaming(StreamingConfig(
    mode=StreamingMode.PROGRESS,
    progress_style="feed",
))

streaming:
  mode: progress
  progress_style: feed
  progress_max_lines: 6

Troubleshooting