Summary

PraisonAI PR #1498 ("fix: Bot has zero tools in daemon/gateway mode — smart defaults + auto-approve now run") was merged into main on 2026-04-22. This PR changes several user-visible behaviors of the bot runtime and gateway. Our existing documentation at docs/features/messaging-bots.mdx now contradicts the SDK on multiple points and must be updated.

Recommended action: CONTENT UPDATE — modify the existing docs/features/messaging-bots.mdx (plus a small gateway doc touch-up). No new page is required — a single new "Smart Defaults" section + targeted updates to existing tables and examples is sufficient.

The auto-generated SDK reference at docs/sdk/reference/praisonaiagents/classes/BotConfig.mdx will be refreshed by the auto-generator and does not need a manual edit.

Why update, not new content

• docs/features/messaging-bots.mdx already exists and already has a "Configuration Options" table listing auto_approve_tools and default_tools with the old values. Creating a second page would cause duplication.
• The new _defaults.py module is internal plumbing — it is not user-facing API. Users only see the effects (safe tools auto-injected, auto-approval on by default). Those effects belong in the existing page.
• The one new user-facing concept is "Smart Defaults" behavior, which fits cleanly as a new section inside the existing page.

What changed in the SDK (ground truth)

1. BotConfig.auto_approve_tools default: False → True

File: src/praisonai-agents/praisonaiagents/bots/config.py

# Before
auto_approve_tools: bool = False

# After
auto_approve_tools: bool = True  # If True, skip confirmation for safe tool execution

Rationale (from MIGRATION_NOTES.md in the PR): chat bots cannot show CLI approval prompts, so manual approval was impractical. Safety is preserved via safe-tool filtering.

2. BotConfig.default_tools — execute_command removed

File: src/praisonai-agents/praisonaiagents/bots/config.py

# Before
default_tools = [
    "execute_command", "search_web", "web_crawl",
    "schedule_add", "schedule_list", "schedule_remove",
    "store_memory", "search_memory",
    "store_learning", "search_learning",
]

# After (safe tools only)
default_tools = [
    "search_web", "web_crawl",
    "schedule_add", "schedule_list", "schedule_remove",
    "store_memory", "search_memory",
    "store_learning", "search_learning",
]

The list is now described as "Default safe tools (auto-injected for bots with no tools configured)".

3. Gateway now applies the same smart defaults as Bot()

File: src/praisonai/praisonai/gateway/server.py (new _create_bot path calls apply_bot_smart_defaults)

Previously, WebSocketGateway._create_bot() bypassed the Bot() wrapper, so agents spawned under praisonai gateway start had zero tools. Now the gateway deep-copies the agent and runs the same smart-defaults logic, so bot start and gateway start produce identical behaviour.

4. New YAML channel options parsed by the gateway

File: src/praisonai/praisonai/gateway/server.py

Per-channel auto_approve_tools and default_tools are now plumbed from YAML into BotConfig:

channels:
  slack:
    token: ${SLACK_BOT_TOKEN}
    auto_approve_tools: true      # NEW — default True; accepts "true"/"1"/"yes"/"on"/"false"/...
    default_tools:                # NEW — overrides BotConfig.default_tools for this channel
      - search_web
      - store_memory

auto_approve_tools accepts both booleans and string forms ("true", "1", "yes", "on", "false", "0", "no", "off", empty string → False). Any destructive tool in default_tools (execute_command, delete_file, write_file, shell_command) is filtered out with a warning unless explicitly opted into.

5. tools: [] in YAML is honoured as explicit opt-out

If a gateway agent YAML contains tools: [] (explicitly empty), the gateway sets agent._explicit_empty_tools = True and smart defaults are not injected. Omitting the tools: key entirely keeps the old behaviour: smart defaults are injected.

6. praisonai onboard wizard output changed

File: src/praisonai/praisonai/cli/features/onboard.py

Generated bot.yaml now includes:

• Appended instruction hint: "... You can search the web, manage schedules, and remember past conversations. Use your tools proactively."
• Commented-out tools: [] override hint under agent: and agents.<name>:
• Commented-out auto_approve_tools: true hint under each channel
• Instruction strings are YAML-escaped (backslashes and quotes)

Concrete documentation changes required

All edits are to docs/features/messaging-bots.mdx unless noted otherwise. Keep the agent-centric, "feel how easy this is" tone per AGENTS.md.

Edit 1 — "Configuration Options" table and code block

Current file has (around the middle of the page):

config = BotConfig(
    ...
    auto_approve_tools=False,       # Auto-approve tool executions (skip confirmation)
)

and the table row:

| default_tools | list | ["execute_command", ...] | Default tools enabled for all bots |
| auto_approve_tools | bool | False | Skip tool execution confirmation (for trusted environments) |

Change to:

config = BotConfig(
    ...
    auto_approve_tools=True,        # Auto-approve safe tool executions (default: True for chat bots)
)

Edit 2 — Add a new "Smart Defaults" section

Insert immediately after "How It Works" and before "Socket Mode vs Webhook". Use a Mermaid diagram with the standard colour scheme. Suggested content:

## Smart Defaults

Bots ship with sensible defaults so you can start chatting immediately — no tool wiring required.

```mermaid
graph LR
    A[🤖 Agent<br/>tools=None] --> SD[⚙️ Smart Defaults]
    SD --> T[🔍 search_web<br/>📅 schedule_*<br/>🧠 memory<br/>📚 learning]
    SD --> AA[✅ auto-approve<br/>for safe tools]
    SD --> H[💬 session history<br/>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 |

<Warning>
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.
</Warning>

<Info>
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.
</Info>

Edit 3 — Update "Multi-Channel Gateway" YAML example

The existing gateway.yaml example in the "Multi-Channel Gateway" section should showcase the new channel-level overrides. Add to the example:

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
      default: support

Add a callout: "The gateway now produces identical results to Bot() — agents get the same safe tools and auto-approval in both entry points."

Edit 4 — "Best Practices" accordion — add two entries

<Accordion title="Keep destructive tools off by default">
  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).
</Accordion>

<Accordion title="When to set auto_approve_tools=false">
  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.
</Accordion>

Edit 5 — Update "Zero-Code Mode" YAML example

The current bot.yaml example under "Zero-Code Mode" lists tools: [search_web]. Add a note immediately after that block:

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.

Edit 6 — Update generated onboard output reference (if present)

If docs/features/messaging-bots.mdx (or any related onboard doc) shows a sample of praisonai onboard output, regenerate it to match the new wizard output, which now includes:

• The appended "You can search the web, manage schedules..." hint in instructions
• Commented-out tools: [] override lines
• Commented-out auto_approve_tools: true hints per channel

Edit 7 — docs/features/gateway.mdx (if it exists)

If there is a dedicated gateway page, add a one-paragraph "Parity with Bot()" note stating that gateway start now applies the same smart defaults as bot start, resolving the previous "zero tools in daemon mode" issue (fixes #1496).

Agent-centric Quick Start (for the new Smart Defaults section)

Per AGENTS.md rule 9 ("Documentation need to be agent centric. Top of the document should always start with Agent Centric code example"), include this minimal example near the top of the new section:

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

And for CLI users:

# Same result — no YAML tool list needed
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

User interaction flow (for the section diagram)

Per AGENTS.md rule 10, show the real interaction:

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

Files to touch

Verification checklist (per AGENTS.md §9)

• Frontmatter unchanged (title, sidebarTitle, description, icon still correct)
• New "Smart Defaults" section has hero Mermaid diagram with standard colours (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1, white text)
• auto_approve_tools default shown as True in both the code block and the config table
• default_tools list matches SDK (no execute_command)
• Destructive-tool filtering is called out
• tools: [] opt-out is documented
• Gateway parity with Bot() is documented
• "Best Practices" accordion gains the two new entries
• All code examples runnable — imports use from praisonaiagents import Agent and from praisonai.bots import ...
• Writing follows AGENTS.md §6 rules (concise, active voice, no forbidden phrases)

References

• Source PR: fix: Bot has zero tools in daemon/gateway mode — smart defaults + auto-approve now run PraisonAI#1498
• Original issue: Bot has zero tools in daemon/gateway mode — smart-defaults + auto-approve never run (same bug shape as #1495) PraisonAI#1496
• Migration notes: MIGRATION_NOTES.md in the PR root (also reproduced above)
• SDK config file: src/praisonai-agents/praisonaiagents/bots/config.py (mirrored at praisonaiagents/bots/config.py in this repo)
• Gateway server: src/praisonai/praisonai/gateway/server.py
• Smart defaults module: src/praisonai/praisonai/bots/_defaults.py
• Onboard wizard: src/praisonai/praisonai/cli/features/onboard.py

/cc @MervinPraison