Quick Start
1
Create a Bot
import { BotConfig, BotProtocol } from 'praisonai';
const config: BotConfig = {
name: "MyBot",
token: process.env.BOT_TOKEN,
prefix: "!",
channels: ["general", "support"]
};
2
Handle Messages
class MyBot implements BotProtocol {
name = "MyBot";
config: BotConfig;
constructor(config: BotConfig) {
this.config = config;
}
async connect() {
console.log("Bot connected!");
}
async disconnect() {
console.log("Bot disconnected!");
}
async sendMessage(channel: string, content: string) {
// Send message to channel
return { id: "msg-1", content, ... };
}
onMessage(handler: (msg: BotMessage) => void) {
// Register message handler
}
}
Bot Types
BotConfig
interface BotConfig {
name: string; // Bot name
token?: string; // Authentication token
prefix?: string; // Command prefix (e.g., "!")
channels?: string[]; // Allowed channels
allowedUsers?: string[]; // Allowed user IDs
metadata?: Record<string, any>;
}
BotUser
interface BotUser {
id: string; // User ID
name: string; // Username
displayName?: string; // Display name
isBot?: boolean; // Is this a bot?
metadata?: Record<string, any>;
}
BotChannel
interface BotChannel {
id: string; // Channel ID
name: string; // Channel name
type: 'text' | 'voice' | 'dm' | 'group';
metadata?: Record<string, any>;
}
BotMessage
interface BotMessage {
id: string; // Message ID
content: string; // Message content
author: BotUser; // Message author
channel: BotChannel; // Channel
timestamp: Date; // When sent
attachments?: Array<{
url: string;
type: string;
name?: string;
}>;
metadata?: Record<string, any>;
}
Bot Protocol
interface BotProtocol {
name: string;
config: BotConfig;
connect(): Promise<void>;
disconnect(): Promise<void>;
sendMessage(channel: string, content: string): Promise<BotMessage>;
onMessage(handler: (message: BotMessage) => void | Promise<void>): void;
getUser(userId: string): Promise<BotUser | null>;
getChannel(channelId: string): Promise<BotChannel | null>;
}
Gateway Types
GatewayConfig
interface GatewayConfig {
url: string; // Gateway URL
apiKey?: string; // API key
timeout?: number; // Request timeout (ms)
retryAttempts?: number; // Retry count
retryDelay?: number; // Delay between retries (ms)
metadata?: Record<string, any>;
}
GatewayMessage
interface GatewayMessage {
id: string;
type: 'request' | 'response' | 'event' | 'error';
payload: any;
timestamp: Date;
correlationId?: string;
metadata?: Record<string, any>;
}
GatewayEvent
interface GatewayEvent {
type: string; // Event type
data: any; // Event data
timestamp: Date;
source?: string; // Event source
metadata?: Record<string, any>;
}
Gateway Protocol
interface GatewayProtocol {
config: GatewayConfig;
connect(): Promise<void>;
disconnect(): Promise<void>;
isConnected(): boolean;
send(message: GatewayMessage): Promise<void>;
receive(): Promise<GatewayMessage | null>;
onEvent(handler: (event: GatewayEvent) => void | Promise<void>): void;
onError(handler: (error: Error) => void): void;
}
Failover Manager
Handle provider failover for high availability:import { FailoverManager, FailoverConfig, ProviderStatus } from 'praisonai';
const config: FailoverConfig = {
providers: ["openai", "anthropic", "google"],
maxRetries: 3,
retryDelay: 1000,
healthCheckInterval: 30000
};
const manager = new FailoverManager(config);
// Get next available provider
const provider = manager.getNextProvider();
// Mark provider as failed
manager.markFailed("openai");
// Check provider status
const status = manager.getStatus("openai");
// Returns: ProviderStatus.HEALTHY | DEGRADED | FAILED
Autonomy Levels
import { AutonomyLevel } from 'praisonai';
AutonomyLevel.NONE // No autonomous actions
AutonomyLevel.LOW // Minimal autonomy
AutonomyLevel.MEDIUM // Moderate autonomy
AutonomyLevel.HIGH // High autonomy
AutonomyLevel.FULL // Full autonomy
Sandbox Types
import { SandboxStatus, SandboxResult, SandboxProtocol } from 'praisonai';
// Sandbox status
SandboxStatus.IDLE
SandboxStatus.RUNNING
SandboxStatus.COMPLETED
SandboxStatus.FAILED
SandboxStatus.TIMEOUT
// Sandbox result
interface SandboxResult {
status: SandboxStatus;
output?: string;
error?: string;
executionTime?: number;
metadata?: Record<string, any>;
}
Common Patterns
- Slack Bot
- Gateway Client
import { BotProtocol, BotConfig, BotMessage, Agent } from 'praisonai';
class SlackBot implements BotProtocol {
name = "SlackBot";
config: BotConfig;
private agent: Agent;
constructor(config: BotConfig) {
this.config = config;
this.agent = new Agent({
name: "SlackAssistant",
instructions: "Help users in Slack"
});
}
onMessage(handler: (msg: BotMessage) => void) {
// When message received
this.handleMessage = async (msg) => {
if (msg.content.startsWith(this.config.prefix!)) {
const query = msg.content.slice(1);
const response = await this.agent.start(query);
await this.sendMessage(msg.channel.id, response);
}
};
}
}
import { GatewayProtocol, GatewayConfig, GatewayMessage } from 'praisonai';
class WebSocketGateway implements GatewayProtocol {
config: GatewayConfig;
private ws: WebSocket | null = null;
constructor(config: GatewayConfig) {
this.config = config;
}
async connect() {
this.ws = new WebSocket(this.config.url);
await new Promise((resolve) => {
this.ws!.onopen = resolve;
});
}
async send(message: GatewayMessage) {
this.ws?.send(JSON.stringify(message));
}
isConnected() {
return this.ws?.readyState === WebSocket.OPEN;
}
}
API Reference
BotProtocol
Bot protocol interface
GatewayProtocol
Gateway protocol interface
Best Practices
Use failover for reliability
Use failover for reliability
Configure multiple providers with
FailoverManager for high availability.Handle disconnections gracefully
Handle disconnections gracefully
Implement reconnection logic in your bot’s
connect() method.Rate limit message handling
Rate limit message handling
Add rate limiting to prevent overwhelming your agent with messages.
Related
Slack Bot
Build Slack integrations
Voice
Voice-enabled agents