> ## 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
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 bot with `group_policy: observe`.
`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**. | 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. | 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
```
***
## 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
Only Telegram honours `observe` today. Other adapters gate solely on `mention_required` and fall back to their default group handling.
| Platform | `observe` supported? |
| -------- | -------------------- |
| Telegram | ✅ |
| Slack | ❌ (planned) |
| Discord | ❌ (planned) |
| WhatsApp | ❌ (planned) |
***
## Best Practices
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.
`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 always run the agent regardless of `group_policy`. `observe` only changes how unmentioned **group** messages are handled.
Every unmentioned message is stored. In busy or sensitive channels, lower `max_history` or enable compaction to summarise older turns.
***
## Related
Share one transcript across a group with sender attribution
Let the agent choose not to reply with NO\_REPLY