Observe Mode

Retain group chat context without replying to every message

observe lets your bot listen to a group without answering — every message lands in the transcript, but the agent only runs when it’s @mentioned.

Diagram

Quick Start

Simple Usage

Write the agent that answers when addressed.

python

from praisonaiagents import Agent

agent = Agent(
    name="Group Assistant",
    instructions="Summarise or answer when addressed. Refer back to what people said.",
)

agent.start("Watches the group; replies only when @mentioned")

Behind the scenes: run this agent through the Telegram, Discord or Slack bot with group_policy: observe.

Gateway YAML (the real switch)

group_policy: observe is the whole change. Add session_scope: per_chat for shared group memory.

yaml

# gateway.yaml
channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}
    group_policy: observe        # ← the whole change
    session:
      session_scope: per_chat    # ← recommended: shared group transcript

agent:
  name: group-assistant
  instructions: |
    You are a group assistant. Reply only when @mentioned.
    You can see the recent group conversation — refer to participants by name.
  model: gpt-4o-mini

How It Works

Unmentioned messages are recorded as passive user turns; the agent only runs on an @mention and sees the full recent conversation.

Diagram

Policy Options

Every group_policy value and when to pick it.

Value	Behaviour	When to use
`respond_all`	Agent runs on every message.	Small trusted groups; expensive.
`mention_only` (default)	Unmentioned messages dropped, no memory. A reply to the bot’s own message is admitted just like an `@mention`.	Safe default. Bot forgets everything until addressed.
`command_only`	Only `/commands` reach the agent.	Command-driven bots.
`observe`	Unmentioned messages stored as passive context. Agent only runs when @mentioned; the reply sees the full recent conversation. A reply to the bot is admitted like an `@mention`.	Group assistants (summarise, refer back, catch up).

Diagram

Interaction Flow

What the group sees versus what the transcript actually holds under observe + per_chat.

Group chat (what everyone sees):
  Alice:  when's the launch?
  Bob:    next friday
  Alice:  @bot summarise
  Bot:    Launch is next Friday.

Session transcript (what the bot stores):
  [Alice] when's the launch?     ← passive, no agent run
  [Bob] next friday              ← passive, no agent run
  [Alice] @bot summarise         ← triggers agent; sees both lines above

The bot stayed silent for the first two messages but still captured them, so the @mention answers with full awareness.

Compatibility

Telegram, Discord and Slack honour observe today — they share one group-admission decision, so the same group_policy behaves identically on all three. The YAML above uses telegram:; discord: and slack: channel entries take the same keys.

Platform	`observe` supported?
Telegram	✅
Slack	✅
Discord	✅
WhatsApp	❌ (planned)

Reply-to-bot on Discord and Slack

Discord: using Discord’s native Reply on one of the bot’s own messages counts as addressing the bot.

Slack: a reply posted in a thread whose parent message was posted by the bot counts as addressing the bot. Top-level channel messages, and threads started under someone else’s message, do not count.

Best Practices

Pair with session_scope: per_chat for shared group memory

Without per_chat, passive turns are keyed under each individual sender’s own session — useful for solo group DMs but not shared. Add session_scope: per_chat so every message lands on the shared per-chat transcript that a later @mention reads from.

Prefer observe over respond_all + NO_REPLY

observe records unmentioned messages without running the agent — no LLM tokens spent, no risk of an accidental reply. respond_all + NO_REPLY runs the agent on every message and then chooses silence, which is more expensive and less safe.

DMs are unaffected

DMs always run the agent regardless of group_policy. observe only changes how unmentioned group messages are handled.

Account for retention and PII

Every unmentioned message is stored. In busy or sensitive channels, lower max_history or enable compaction to summarise older turns.

Per-Chat Session Scope

Share one transcript across a group with sender attribution

Bot Intentional Silence

Let the agent choose not to reply with NO_REPLY

Observe Mode

Quick Start

How It Works

Policy Options

Interaction Flow

Compatibility

Reply-to-bot on Discord and Slack

Best Practices

Related