> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Observe Mode"
        Msg[📨 Group message] --> Mention{@mentioned?}
        Mention -->|No| Record[📝 Record as context]
        Mention -->|Yes| Run[🤖 Run agent]
        Record --> Done[🔇 No reply]
        Run --> Reply[💬 Reply with full context]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    classDef silent fill:#8B0000,stroke:#7C90A0,color:#fff

    class Msg input
    class Mention,Record check
    class Run,Reply result
    class Done silent
```

## Quick Start

**1. Simple Usage**

Write the agent that answers when addressed.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Alice
    participant Bob
    participant Telegram
    participant Session as Session Manager
    participant Agent

    Alice->>Telegram: "when's the launch?"
    Telegram->>Session: record_passive("Alice: when's the launch?")
    Note over Agent: no run

    Bob->>Telegram: "next friday"
    Telegram->>Session: record_passive("Bob: next friday")
    Note over Agent: no run

    Alice->>Telegram: "@bot summarise"
    Telegram->>Session: read transcript
    Session-->>Agent: full [Alice]/[Bob] history + Alice's request
    Agent-->>Telegram: "Launch is next Friday."
    Telegram-->>Alice: reply
```

***

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q[❓ Group behaviour needed] --> A{Must every message trigger the agent?}
    A -->|Yes| Resp[respond_all]
    A -->|No| B{Need group conversation context on @mention?}
    B -->|No| Mo[mention_only]
    B -->|Yes| Ob[observe]
    A -->|Only slash commands| Co[command_only]

    classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef choose fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef pick fill:#10B981,stroke:#7C90A0,color:#fff

    class Q q
    class A,B choose
    class Resp,Mo,Ob,Co pick
```

> [!TIP]
>
> 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](https://praison.ai/docs/features/bot-implicit-mentions.md) 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

> [accordion] 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.

> [accordion] 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.

> [accordion] DMs are unaffected
>
> DMs always run the agent regardless of `group_policy`. `observe` only changes how unmentioned **group** messages are handled.

> [accordion] 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

> [card] [Per-Chat Session Scope](https://praison.ai/docs/features/per-chat-session-scope.md)
>
> Share one transcript across a group with sender attribution

> [card] [Bot Intentional Silence](https://praison.ai/docs/features/bot-intentional-silence.md)
>
> Let the agent choose not to reply with NO\_REPLY


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.