Bot Intentional Silence

Bot platform adapters now ship in the praisonai-bot package. praisonai bot serve still works exactly as documented here; for a standalone install see praisonai-bot Migration.

With allow_silence: true, an agent can return NO_REPLY (or a custom token) to send nothing — no message, no typing indicator, no error.

Both NO_REPLY (this page) and BotLoopGuard live in praisonaiagents/bots/silence.py alongside classify_final(), the classifier every adapter uses to distinguish silence from an empty reply. Where NO_REPLY lets an agent opt out of a single reply, BotLoopGuard lets the gateway opt out of an entire runaway bot-to-bot exchange.

from praisonaiagents import Agent

agent = Agent(name="group-bot", instructions="Reply in group chats only when helpful.")
agent.start("Should I respond to this off-topic message?")

The user posts in a group chat; with allow_silence: true, the agent can return NO_REPLY so nothing is sent.

Silence via NO_REPLY happens after the agent runs — the agent decides not to reply. The observe group_policy is different: it skips the agent-run branch entirely for unmentioned messages, but still writes them to the session as passive context. Use NO_REPLY when the agent should judge each message; use observe to retain group chatter without ever running the agent on it. See observe: passive group context.

Quick Start

YAML

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    group_policy: respond_all
    allow_silence: true

Python

from praisonai.bots import Bot
from praisonaiagents import Agent

agent = Agent(
    name="Group Helper",
    instructions="Reply only when asked a direct question. Otherwise return exactly NO_REPLY.",
)
bot = Bot("telegram", agent=agent, allow_silence=True)
bot.run()

How It Works

Marker	Honoured when `allow_silence=true`
`NO_REPLY`	✅ default token
`[SILENT]`	✅
`SILENT`	✅
Custom `silence_token`	✅ exact match only
Prose containing “NO_REPLY”	❌ not treated as silence

Scheduled agents

An unattended monitor with nothing to report returns a silence marker, and the scheduled run skips delivery to chat while still recording as succeeded. Scheduled and automation runs honour the same silence contract — a scheduled job whose whole output is NO_REPLY, [SILENT], or SILENT skips delivery while the run still completes and is recorded as succeeded in history. An intentional-silence run also skips the continuable-session seed — nothing was delivered, so nothing is claimed to have been. The next inbound message lands as a fresh turn, same as before. See Scheduler Delivery → Continuable Delivery.

No opt-in flag on scheduled paths. Ambient/group-chat silence requires allow_silence: true. Scheduled and automation delivery honour markers unconditionally — an unattended monitor spamming NO_REPLY into chat is never useful.

from praisonaiagents import Agent

monitor = Agent(
    name="log-watcher",
    instructions=(
        "Check the error log summary. If there are new errors, list them. "
        "If the summary is empty, reply with exactly: NO_REPLY"
    ),
)
# Wire this agent into a scheduled job (see /docs/features/scheduled-run-policy).
# On empty-log runs, nothing lands in chat; job still shows 'succeeded' in history.

Marker	Ambient / group chat (`allow_silence: true`)	Scheduled / automation delivery (always)
`NO_REPLY`	✅ default token	✅
`[SILENT]`	✅	✅
`SILENT`	✅	✅
Whitespace-wrapped marker (`" NO_REPLY "`)	✅	✅
Custom `silence_token` (ambient-only opt-in)	✅ exact match	not applicable — scheduled path uses default markers only
Prose containing `"NO_REPLY"`	❌	❌

Both the wrapper (AgentScheduler) and bot (ScheduledAgentExecutor) paths behave identically here — you don’t need to know which one you’re on.

Configuration

Field	Type	Default	Description
`allow_silence`	`bool`	`false`	Honour silence markers (opt-in)
`silence_token`	`str`	`None`	Override marker; when set, only this exact string triggers silence

Combine with group_policy: respond_all so the agent may respond, then chooses silence via NO_REPLY.

Scheduled Runs

The same silence markers also suppress delivery on scheduled runs — AgentScheduler, AsyncAgentScheduler, and the full-gateway ScheduledAgentExecutor all honour NO_REPLY / [SILENT] / SILENT.

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(
    name="Watchdog",
    instructions=(
        "Every hour, check for new alerts. "
        "If there are none, reply with exactly: NO_REPLY."
    ),
)
AgentScheduler(agent, task="Hourly check", deliver="telegram:123456").start("hourly")

On the scheduled path, silence handling is always on — there is no allow_silence toggle. An unattended monitor should never post the raw control token, so the marker unconditionally suppresses delivery. The run is still recorded as succeeded.

As on the chat path, only an exact marker triggers silence — prose mentioning NO_REPLY is delivered normally. See Scheduler Delivery → Intentional Silence for the full flow.

Visible-Outcome Guarantee for Empty Finals

Blank replies and [tool_calls: …] placeholders now get a recorded fallback instead of silently dropping. classify_final() is the single decision point every adapter (Slack, Telegram, Discord, IRC, custom) uses to classify an agent’s final reply. A deliberate NO_REPLY is still suppressed, but an empty final — blank, whitespace-only, or the machine [tool_calls: …] placeholder — now gets a visible fallback message so no adapter ends a turn with nothing shown.

Final reply	`classify_final()`	Category	Delivery
`NO_REPLY`, `[SILENT]`, `SILENT`	`"silence"`	Deliberate silence	Suppressed — the no-reply contract
Blank, whitespace-only, `[tool_calls: …]`	`"empty"`	Empty, not silence	Fallback message substituted
Any real content	`"text"`	Normal reply	Delivered as-is

Override the fallback message

The default fallback is "Task completed — no message to show.". Override it via either an empty_final_message key on the existing BotConfig.metadata block (recommended — no new typed knob) or a direct config.empty_final_message attribute.

channels:
  slack:
    type: slack
    token: env:SLACK_BOT_TOKEN
    metadata:
      empty_final_message: "The agent completed the task but produced no reply text."

from praisonai.bots import BotConfig

config = BotConfig(token="env:SLACK_BOT_TOKEN")
config.empty_final_message = "Task done — nothing to display."

Every fallback emission is logged at INFO level so the recorded non-outcome is operator-visible:

Empty-final resolution: substituted fallback for a blank/placeholder reply on <platform> (visible-outcome guarantee)

A tool-only run now still delivers a visible reply — the custom fallback if configured, the default otherwise:

from praisonaiagents import Agent

agent = Agent(
    instructions="Help the user with quick tasks.",
    # A run that only calls tools now still delivers a visible reply
    # (custom fallback if configured, default otherwise).
)
agent.start("Just log this event, no reply needed.")

Best Practices

Opt in explicitly

allow_silence defaults to false — existing bots behave unchanged.

Teach the agent the contract

Instructions should say when to return exactly NO_REPLY vs a normal reply.

Use for ambient group channels

Reduces noise when the bot listens to everything but should rarely speak.

Scheduled Run Policy

Guardrails and silent runs for unattended scheduled agents

Bot Loop Protection

Break runaway bot-to-bot reply loops

Gateway

Channel configuration reference

Messaging Bots

Multi-platform bot setup

Scheduler Delivery

Silence markers also suppress scheduled pushes

Failure-path counterpart of classify_final — visible replies for failed turns

​Quick Start

​How It Works

​Scheduled agents

​Configuration

​Scheduled Runs

​Visible-Outcome Guarantee for Empty Finals

​Override the fallback message

​Best Practices

​Related

Scheduled Run Policy

Bot Loop Protection

Gateway

Messaging Bots

Scheduler Delivery

Quick Start

How It Works

Scheduled agents

Configuration

Scheduled Runs

Visible-Outcome Guarantee for Empty Finals

Override the fallback message

Best Practices

Related