Bot Run Control

Responsive UX for bots during long-running agent tasks — busy acknowledgments, /stop, and pending message handling

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

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
agent.start("Research solar energy trends while the user sends follow-ups.")

The user sends a message while a long run is active; the bot acknowledges busy state, queues follow-ups, or honours /stop.

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

STEER lane — when busy_mode="steer" and the agent has message_steering=True:

When run_timeout is exceeded (default 300 seconds), BotSessionManager raises BotRunTimeout and cancels the in-flight run. Timeout failures are not pushed to the DLQ, so slow agents do not retry in a loop.

Choosing a Busy Mode

How STEER Mode Works

• Enable steering on the agent with message_steering=True.
• Set the bot’s busy_mode="steer".
• Mid-run messages are injected into the live turn at SteeringPriority.INTERRUPT (priority 30); the agent picks them up before its next tool-loop step.

Custom integrators embedding chat_with_run_control() must call register_agent(...) on every fresh and pending run inside the drain loop — not only the first run — so STEER always has a live agent handle.

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

RunDecision enum

submit() returns a RunDecision value that tells the bot how to handle the message:

Under busy_mode="interrupt", QUEUED and MERGED can also be returned when the turn is protected (mid-foreground-subagent or mid-compaction), or when a deferred message is already waiting in the pending slot — later messages merge into it so the queued text is never dropped by an interrupt. See Turn Protection Window.

Run metadata

chat_with_run_control returns {"response": str, "metadata": dict}:

Acknowledgment messages:

Queue drain implemented in PR #1980.

Programmatic steering

Inject real-time guidance into a running agent from outside the bot chat — useful for admin hooks, orchestrators, or test harnesses:

agent.steer("Stop summarising — return raw JSON instead", priority=30)

agent.steer(text, priority=30) queues text into the agent’s steering queue at priority 30 (SteeringPriority.INTERRUPT — highest available). The agent picks it up before its next tool-loop step without cancelling the current run.

register_agent / finish_run / stop lifecycle:

Fallback path: If submit() is called with busy_mode="steer" but no agent is registered (session.agent is None) or the agent has message_steering disabled, submit() falls back to QUEUE silently — no error is raised.

Programmatic cancellation

BotSessionManager exposes cancellation for admin hooks or custom integrations:

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

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

# Cancel a specific user's in-flight run (e.g. from an admin endpoint)
bot._session.cancel_run(user_id="123456789", reason="admin_kill")

# See who has a run in progress right now
print(bot._session.get_active_runs())

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 — all follow-ups drained in order after each run
    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())

Real-Time Steering Bot (Steer Mode)

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(
    name="researcher",
    instructions="Research topics deeply and write structured reports.",
    message_steering=True,  # Required for busy_mode="steer" to actually steer
)

bot = TelegramBot(
    token="YOUR_TOKEN",
    agent=agent,
    busy_mode="steer",
    busy_ack="🧭 Steering the current task with your new guidance",
)

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

Example user flow:

User: research solar trends and write a 500-word summary
Bot:  (working — gathering sources…)
User: actually, focus on the EU market only
Bot:  🧭 Steering the current task with your new guidance
Bot:  ✅ EU Solar Market Trends Summary [...] (partial progress preserved)

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

Related