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.

Quick Start

1. Simple Usage

   Write the agent that answers when addressed.

   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.

2. Gateway YAML (the real switch)

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

   # 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.

---

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

Reply-to-bot works on both branches: under mention_only and observe, tapping Reply on the bot’s message admits the follow-up without re-typing @bot. See Implicit Mentions to enable quote/thread signals or turn this off.

---

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.

---

Related

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