Skip to main content
Bot run control provides responsive feedback during long-running agent tasks, eliminating silent blocking where follow-up messages queue invisibly.

​
Quick Start

1

Enable Run Control

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(name="assistant", instructions="Be helpful")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent, busy_mode="interrupt")

import asyncio
asyncio.run(bot.start())
2

Test with Long Task

Send a long-running request like “research solar energy trends” to your bot, then immediately send another message. You’ll get instant feedback instead of silence.
3

Try /stop Command

While the bot is working, send /stop to cancel the current task. The bot responds immediately and starts fresh.

​
How It Works

​
Choosing a Busy Mode

ModeWhen to UseBehavior
queueResearch bots, task completion importantMessages queued, processed in order after current task
interruptInteractive chat, latest intent mattersCancels current task, starts new one immediately
steerReal-time collaboration (experimental)Injects messages into running task (fallback to queue)

​
Configuration Options

Configure run control through BotConfig or directly with bot constructors: 
from praisonaiagents import Agent
from praisonai.bots import TelegramBot

# Via bot constructor
bot = TelegramBot(
    token="YOUR_TOKEN",
    agent=agent,
    busy_mode="queue",
    busy_ack="🕒 Got it — {action}. I'll handle it after this finishes."
)
OptionTypeDefaultDescription
busy_modestr"queue"Policy for mid-run messages. One of "queue", "interrupt", "steer".
busy_ackstr"⏳ {action} — will be considered next"Template for busy acknowledgment. {action} is replaced with "noted" (queued) or "added to pending request" (merged).

BotConfig API Reference

Full configuration options for bot settings

​
Common Patterns

​
Long Research Bot (Queue Mode)

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(
    name="researcher", 
    instructions="Research topics deeply and provide comprehensive analysis"
)

bot = TelegramBot(
    token="YOUR_TOKEN",
    agent=agent,
    busy_mode="queue",  # Preserves work, processes follow-ups in order
    busy_ack="📚 Research noted — {action}. Will incorporate after analysis."
)

import asyncio
asyncio.run(bot.start())

​
Interactive Chat Bot (Interrupt Mode)

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

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

bot = TelegramBot(
    token="YOUR_TOKEN",
    agent=agent,
    busy_mode="interrupt",  # Latest message wins
    busy_ack="⚡ {action} — switching to your latest request"
)

import asyncio
asyncio.run(bot.start())

​
Using /stop Mid-Task

When a bot is processing a long request: 
User: research quantum computing applications
Bot:  (working...)
User: /stop
Bot:  ✅ Current task cancelled. Send a new message to start fresh.
User: what's the weather?
Bot:  (starts new task immediately)

​
Best Practices

Use queue mode for bots that do important work users shouldn’t lose — research bots, analysis tools, content generators. Users get acknowledgments but work continues.Use interrupt mode for conversational bots where the latest message reflects user intent — chat assistants, Q&A bots, real-time helpers.Use steer mode (experimental) for collaborative scenarios where users provide guidance during long tasks. Currently falls back to queue mode.
The /stop command works through the SessionRunControl system. Without run control enabled, bots process messages sequentially with traditional locking, so /stop would queue behind the current task instead of interrupting it.Enable run control by setting busy_mode to any value other than the default.
Each run gets a unique generation number. When a run finishes, it only clears the session state if its generation matches the current one. This prevents cancelled runs from overwriting fresh state when they complete.
Use SessionRunControl.cleanup_stale_sessions(max_age_seconds=3600) to clean up old sessions. This prevents memory leaks in long-running bots and removes abandoned user sessions.

Bot Commands

Built-in chat commands including /stop

Messaging Bots

Complete guide to Telegram, Discord, Slack bots