From f408aea07d3003bc310e8ce58fc0543be5634c1a Mon Sep 17 00:00:00 2001 From: MervinPraison <454862+MervinPraison@users.noreply.github.com> Date: Wed, 22 Apr 2026 08:18:21 +0000 Subject: [PATCH] docs: Update messaging-bots for smart defaults + auto-approve behavioral changes (fixes #219) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update auto_approve_tools default from False to True in config table and code - Update default_tools list to remove execute_command, show only safe tools - Add comprehensive Smart Defaults section with Mermaid diagrams - Update Multi-Channel Gateway example with new channel-level options - Add Best Practices entries for safe tools and approval flow requirements - Add tip about omitting tools in Zero-Code Mode YAML - Update bot-gateway.mdx with parity note between gateway and Bot() modes 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Mervin Praison --- docs/features/bot-gateway.mdx | 2 + docs/features/messaging-bots.mdx | 100 ++++++++++++++++++++++++++++++- 2 files changed, 99 insertions(+), 3 deletions(-) diff --git a/docs/features/bot-gateway.mdx b/docs/features/bot-gateway.mdx index f3580886..0a060001 100644 --- a/docs/features/bot-gateway.mdx +++ b/docs/features/bot-gateway.mdx @@ -26,6 +26,8 @@ flowchart LR Run all your bots from one command. The Gateway Server manages multiple bot connections and routes messages to the right AI agent. +**Parity with Bot()**: `praisonai gateway start` now applies the same smart defaults as `praisonai bot start`, resolving the previous "zero tools in daemon mode" issue. Both entry points produce identical behavior with safe tools auto-injected and auto-approval enabled by default. + ## Quick Start diff --git a/docs/features/messaging-bots.mdx b/docs/features/messaging-bots.mdx index 9c05fd4f..cb1b0232 100644 --- a/docs/features/messaging-bots.mdx +++ b/docs/features/messaging-bots.mdx @@ -293,6 +293,84 @@ The streaming bridge hooks into the same `StreamEventEmitter` used by the web ch --- +## Smart Defaults + +Bots ship with sensible defaults so you can start chatting immediately — no tool wiring required. + +```mermaid +graph LR + A[🤖 Agent
tools=None] --> SD[⚙️ Smart Defaults] + SD --> T[🔍 search_web
📅 schedule_*
🧠 memory
📚 learning] + SD --> AA[✅ auto-approve
for safe tools] + SD --> H[💬 session history
last 20 messages] + + classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff + classDef config fill:#6366F1,stroke:#7C90A0,color:#fff + classDef tools fill:#189AB4,stroke:#7C90A0,color:#fff + classDef result fill:#10B981,stroke:#7C90A0,color:#fff + + class A agent + class SD config + class T tools + class AA,H result +``` + +Both `praisonai bot start` and `praisonai gateway start` apply the same defaults: + +| Default | Applied when | What you get | +|---------|--------------|--------------| +| Safe tools | Agent has no `tools` configured | `search_web`, `web_crawl`, `schedule_*`, `store_memory`/`search_memory`, `store_learning`/`search_learning` | +| Auto-approval | `auto_approve_tools=True` (default) | Tool calls run without CLI prompts — chat bots can't show them anyway | +| Session history | Agent has no `memory` configured | Last 20 messages remembered per user, zero-dep | + +### Opting out + +| Goal | How | +|------|-----| +| Run with **zero** tools | Set `tools: []` explicitly in YAML, or pass `tools=[]` to `Agent` | +| Require manual approval | Set `auto_approve_tools: false` in the channel config | +| Override the tool list | Set `default_tools: [...]` under the channel — destructive tools are still filtered | + + +Destructive tools (`execute_command`, `delete_file`, `write_file`, `shell_command`) are **never auto-injected**, even if you add them to `default_tools`. Wire them explicitly on the agent and add a chat-level approval flow. + + + +Upgrading from an older release? `auto_approve_tools` used to default to `False`. If your bot relied on manual approval, set `auto_approve_tools: false` explicitly. + + +```python +from praisonaiagents import Agent +from praisonai.bots import Bot + +# Zero config — gets search_web, schedule_*, memory, learning, and auto-approval +agent = Agent(name="assistant", instructions="Help the user") +bot = Bot("telegram", agent=agent) +bot.run() +``` + +```bash +# Same result — no YAML tool list needed +praisonai bot telegram --token $TELEGRAM_BOT_TOKEN +``` + +```mermaid +sequenceDiagram + participant U as 👤 User (Telegram) + participant B as 🤖 Bot + participant A as 🧠 Agent + participant T as 🔍 search_web + + U->>B: "What's the latest on Llama 4?" + B->>A: Forward message (no tool prompt) + A->>T: auto-approved call + T-->>A: Results + A-->>B: Answer + B-->>U: 📰 Here's the latest... +``` + +--- + ## Socket Mode vs Webhook PraisonAI bots support two connection modes: @@ -345,7 +423,7 @@ config = BotConfig( reply_in_thread=False, # Reply in threads (default: inline) thread_threshold=500, # Auto-thread if response > N chars (0 = disabled) group_policy="mention_only", # Group chat policy: respond_all, mention_only, command_only - auto_approve_tools=False, # Auto-approve tool executions (skip confirmation) + auto_approve_tools=True, # Auto-approve safe tool executions (default: True for chat bots) ) ``` @@ -363,8 +441,8 @@ config = BotConfig( | `reply_in_thread` | `bool` | `False` | Always reply in threads | | `thread_threshold` | `int` | `500` | Auto-thread responses longer than N chars (0 = disabled) | | `group_policy` | `str` | `"mention_only"` | Group chat behavior: `respond_all`, `mention_only`, or `command_only` | -| `default_tools` | `list` | `["execute_command", ...]` | Default tools enabled for all bots | -| `auto_approve_tools` | `bool` | `False` | Skip tool execution confirmation (for trusted environments) | +| `default_tools` | `list[str]` | `["search_web", "web_crawl", "schedule_add", "schedule_list", "schedule_remove", "store_memory", "search_memory", "store_learning", "search_learning"]` | Safe tools auto-injected when the agent has no tools configured. Destructive tools (`execute_command`, `delete_file`, `write_file`, `shell_command`) are excluded from auto-injection even if listed. | +| `auto_approve_tools` | `bool` | `True` | Skip confirmation for safe tool execution. Chat bots can't show CLI approval prompts, so this defaults to `True`. Set `False` to require approval (only useful if you wire a chat-level approval flow). | | `retry_attempts` | `int` | `3` | Number of retry attempts for failed operations | | `polling_interval` | `float` | `1.0` | Interval for polling mode (seconds) | @@ -1198,6 +1276,10 @@ channels: slack: token: "${SLACK_BOT_TOKEN}" app_token: "${SLACK_APP_TOKEN}" + auto_approve_tools: true # NEW (default: true for chat bots) + # default_tools: # NEW — override the safe tool list per channel + # - search_web + # - store_memory routing: dm: "personal" channel: "support" @@ -1223,6 +1305,8 @@ channels: praisonai gateway --config gateway.yaml ``` +The gateway now produces identical results to `Bot()` — agents get the same safe tools and auto-approval in both entry points. + ```mermaid graph LR T[Telegram]:::platform --> GW[Gateway]:::tool @@ -1265,6 +1349,8 @@ agent: praisonai bot start --config bot.yaml ``` +> **Tip:** You can omit `tools:` entirely — the bot auto-injects safe defaults (`search_web`, schedule, memory, learning). Keep `tools: []` only if you want the bot to run with zero tools. + The `.env` file in the current directory is auto-loaded, so you can store tokens there and reference them with `${VAR_NAME}` syntax. @@ -1345,6 +1431,14 @@ Web mode uses a reverse-engineered protocol. Your number may be banned by Meta. Configure `retry_attempts` and implement exponential backoff for API rate limits. + + + The default tool list is intentionally safe (`search_web`, `schedule_*`, memory/learning). Tools like `execute_command` require explicit opt-in and should be paired with an approval backend. See [Approval Protocol](/features/approval-protocol). + + + + Only set `auto_approve_tools: false` if you've wired a chat-level approval flow (e.g. `SlackApproval`). Otherwise tool calls will hang silently waiting for a CLI prompt the user cannot see. + ## Multi-Agent Configuration