Skip to content

docs: Document 3 new features from PraisonAI PR #1504 #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MervinPraison wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Document 3 new features from PraisonAI PR #1504 #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,7 @@
"docs/features/bot-commands",
"docs/features/bot-gateway",
"docs/features/bot-routing",
"docs/features/bot-pairing",
"docs/features/botos",
"docs/features/push-notifications"
]
Expand Down Expand Up @@ -649,6 +650,8 @@
"pages": [
"docs/features/cli",
"docs/features/async-agent-scheduler",
"docs/features/clarify-tool",
"docs/features/tool-availability",
"docs/features/hooks",
"docs/features/hook-events",
"docs/features/dynamic-variables",
Expand Down
87 changes: 48 additions & 39 deletions docs/best-practices/bot-security.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,17 @@ graph LR

```python
from praisonaiagents import Agent
from praisonaiagents.bots import BotConfig

# Secure bot with allowlist
config = BotConfig(
allowed_users=["@your_username", "123456789"],
unknown_user_policy="deny" # Default secure behavior
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The unknown_user_policy parameter is not defined in the BotConfig class in praisonaiagents/bots/config.py. Using this parameter will result in a TypeError at runtime. Please ensure the documentation matches the current SDK implementation.

)

agent = Agent(
instructions="You are a helpful assistant",
# Note: Security features shown are conceptual
# Actual implementation may vary
# Bot configuration handled by adapter
)
```

Expand All @@ -49,12 +54,19 @@ agent = Agent(

```python
from praisonaiagents import Agent
from praisonaiagents.bots import BotConfig

# Production security setup with pairing
config = BotConfig(
allowed_users=["@admin_user"],
unknown_user_policy="pair", # Secure pairing flow
auto_approve_tools=True, # For bot environments
group_policy="mention_only" # Only respond when mentioned
)

# Production security setup
agent = Agent(
instructions="Secure production assistant",
# Security configuration would go here
# when implemented in the SDK
# Configure with your bot adapter
)
```

Expand Down Expand Up @@ -214,66 +226,63 @@ WhatsApp has the **strongest security defaults** and serves as the reference imp

## Gateway Pairing

<Warning>
**Note:** The pairing system described below represents planned functionality. Current SDK implementation may differ. Verify against actual SDK documentation.
</Warning>

For production deployments, use **gateway pairing** to authorize channels dynamically:
For production deployments, use **gateway pairing** to authorize channels dynamically with the shipped pairing system:

### 1. Set Gateway Secret

```bash
export PRAISONAI_GATEWAY_SECRET="your-secure-secret-key"
```

<Warning>
Without `PRAISONAI_GATEWAY_SECRET`, pairing codes will **not persist across restarts**. Set this in production.
</Warning>
<Note>
The gateway secret is optional - if unset, a per-install secret is auto-generated at `<store_dir>/.gateway_secret` with `0600` permissions and reused across restarts.
</Note>

### 2. Generate Pairing Code
### 2. Enable Pairing Policy

```python
# Note: This API is conceptual - verify implementation
from praisonaiagents.gateway.pairing import PairingStore
from praisonaiagents.bots import BotConfig

config = BotConfig(
allowed_users=["@owner"],
unknown_user_policy="pair" # Enable pairing for unknown users
)

store = PairingStore()
code = store.generate_code(channel_type="telegram")
print(f"Pairing code: {code}") # 8-character hex code
# Unknown users will automatically receive pairing codes when they DM the bot
```

### 3. Verify in Channel
### 3. Approve Pairing Requests

Send the code to your bot in the target channel:
When unknown users DM your bot, they receive pairing codes. Approve them via CLI:

```bash
# User receives: "Your pairing code: ABCD1234"
# Owner approves:
praisonai pairing approve telegram ABCD1234 --label "alice"
```
/pair abc12345
```

The bot will verify the HMAC signature and authorize the channel.
### 4. Manage Pairings

```bash
# List all paired channels
praisonai pairing list

### 4. Check Status
# Revoke access for specific channel
praisonai pairing revoke telegram 987654321

```python
# Check if channel is paired
# Note: Verify this API exists in current SDK
paired = store.is_paired("@username", "telegram")
print(f"Channel paired: {paired}")

# List all paired channels
for channel in store.list_paired():
print(f"{channel.channel_type}: {channel.channel_id}")
# Clear all pairings
praisonai pairing clear --confirm
```

## Doctor Security Check
<Tip>
For detailed pairing documentation, see the [Bot Pairing](/docs/features/bot-pairing) guide.
</Tip>

<Warning>
**Note:** The doctor command shown may not be available in current SDK version. Verify implementation status.
</Warning>
## Doctor Security Check

Use the built-in doctor to audit your bot security configuration:

```bash
# Note: Verify this command exists
praisonai doctor --category bots
```

Expand Down
Loading