A professional-grade Node.js/TypeScript SDK and CLI for building AI agents on the SuperDapp platform. This SDK provides a unified interface for creating intelligent bots that can interact with users, handle commands, and integrate with multiple large language models.

SuperDapp agents use a webhook-based architecture for maximum portability and simplicity.

• Centralized command/message routing in the SDK runtime
• Lightweight lifecycle: you instantiate an agent, register handlers, and pass incoming webhook bodies to it
• Pluggable command and message handlers
• Interactive UI support (buttons, multiselect, reply markup)
• Event dispatch built-in (CommandRegistry + WebhookAgent handle command routing and generic messages)
• Signature validation is application-level: validate incoming requests (e.g., in your Express/Worker handler) before calling agent.processRequest
• Works with any HTTP hosting (Node.js, serverless, etc.)

This is the default architecture for all SuperDapp agents.

• ✅ Complete Webhook Support - Full webhook-based agent architecture
• ✅ Enhanced CLI - New create command and improved project management
• ✅ Interactive UI - Advanced button layouts and multiselect support
• ✅ Multi-Platform Deployment - Cloudflare Workers, AWS Lambda and Docker
• ✅ Comprehensive Documentation - Complete guides and API reference
• ✅ TypeScript Support - Full type safety and IntelliSense
• ✅ Testing Framework - Jest setup with utilities and mocks

You can now use a positional argument for the project directory:

superagent create my-awesome-agent

superagent create my-agent cd my-agent npm install superagent configure superagent run

• superagent create [directory] – Create a new agent project (supports positional or --name)
• superagent configure – Configure API keys and environment variables
• superagent run – Run the agent locally for testing (supports multiple environment file formats)

The superagent run command automatically detects your runtime and supports multiple environment file formats:

• Node.js: .env files
• AWS Lambda: env.json files
• Cloudflare Workers: .dev.vars files

The CLI auto-detects formats; see docs/CLI Guide for details.

• 🤖 Model-Agnostic AI Integration: Seamlessly work with OpenAI, Gemini, Claude, and other LLMs
• 💬 Real-time Messaging: Built-in support for channels and direct messages
• 🔧 CLI Tools: AWS Amplify-inspired CLI for project management and deployment
• 📱 Command Handling: Structured command routing and message processing
• 🔄 Webhook Architecture: Modern webhook-based agent architecture
• 🎨 Interactive UI: Support for buttons, multiselect, and reply markup
• ⚡ Serverless Ready: Ready for deployment to various platforms
• 🛠️ TypeScript First: Full type safety with comprehensive TypeScript support
• 🧪 Testing Ready: Jest setup with comprehensive test utilities

npm install @superdapp/agents

yarn add @superdapp/agents

pnpm add @superdapp/agents

For local development and testing, see DEVELOPMENT.md for instructions on setting up the development environment using npm link.

For advanced development patterns and best practices, see our API Reference.

npm install -g @superdapp/agents

For comprehensive documentation, visit our Documentation Hub:

• Quick Start Guide - Get up and running in minutes
• CLI Guide - Complete command-line interface documentation
• API Reference - Complete SDK reference
• Deployment Guide - Deploy to production
• Tunneling (ngrok) - Expose your local webhook

The SDK client currently covers the core messaging flows:

• Channel and connection messages (send, update, delete)
• Join/leave social groups
• Fetch bot info and user channels

Additional endpoints (media uploads, reactions, typing status, etc.) can be added incrementally; open an issue if you need one prioritized.

See the API reference and /examples for details.

Integrate with node-schedule for periodic tasks:

import { schedule } from '@superdapp/agents'; // Schedule daily news updates schedule.scheduleJob('0 9 * * *', async () => { const news = await generateDailyNews(); await agent.sendChannelMessage('news-channel', news); });

The client includes Axios interceptors for basic request/response logging and error propagation. Wrap your command handlers in try/catch and surface actionable messages to users as needed.

Full TypeScript support with comprehensive types:

import type { MessageData, CommandHandler, BotConfig, ApiResponse, } from '@superdapp/agents'; const handleCommand: CommandHandler = async ({ message, replyMessage, roomId }) => { // Fully typed message object const messageText = (message.body as any)?.m?.body; // ... handler logic };

The SDK includes comprehensive error handling:

try { // Process webhook request await agent.processRequest(webhookBody); } catch (error) { if (error.message.includes('API_TOKEN')) { console.error('Invalid API token. Run: superagent configure'); } else { console.error('Request processing failed:', error); } }

1. Never commit API tokens to version control
2. Use environment variables for sensitive configuration
3. Validate all user inputs before processing
4. Implement rate limiting for command handlers
5. Use HTTPS for all API communications

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

• 📖 Documentation Hub - Complete SDK documentation
• 💬 Discord Community
• 🐛 Issue Tracker
• 📧 Email Support

Built with ❤️ by the SuperDapp Team