Agent Router

A pluggable service that connects LLM agents to users across Slack, Email, and Discord channels. Agent Router provides a unified interface for routing messages, maintaining conversation context, and forwarding communication between channels and agent backends.

📦 Packages

This repository contains both Python and JavaScript implementations:

🐍 Python Package (py/)

The core Agent Router service built with FastAPI and Redis.

• Package: agent-router on PyPI
• Install: pip install agent-router
• Use Case: Running the Agent Router service, building agent backends
• Documentation: py/README.md

🟨 JavaScript Package (js/)

TypeScript client library and React components for integrating with Agent Router.

• Package: @agent-router/client on npm
• Install: npm install @agent-router/client
• Use Case: Building web UIs, integrating with React apps, API client
• Documentation: js/README.md

🏗️ Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Slack     │    │    Email     │    │   Discord   │
│  Webhook    │    │  IMAP/SMTP   │    │    Bot      │
└─────┬───────┘    └──────┬───────┘    └─────┬───────┘
      │                   │                  │
      └───────────────────┼──────────────────┘
                          │
                    ┌─────▼─────┐
                    │   Agent   │
                    │  Router   │ ← py/ package
                    │ (FastAPI) │
                    └─────┬─────┘
                          │
   ┌──────────────────────┼──────────────────────┐
   │                      │                      │
   │            ┌─────────▼─────────┐            │
   │            │       Redis       │            │
   │            │   Memory Store    │            │
   │            └───────────────────┘            │
   │                                             │
   │  ┌─────────────┐              ┌───────────────┐
   │  │   Your      │              │  Web App      │
   │  │   Agent     │              │ (js/ client)  │ ← js/ package
   │  │  Backend    │              │               │
   │  │ (REST API)  │              │  ┌─────────┐  │
   │  └─────────────┘              │  │ Chat UI │  │
   │                               │  └─────────┘  │
   └───────────────────────────────┴───────────────┘

🚀 Quick Start

1. Run the Agent Router Service (Python)

# Install the Python package
pip install agent-router

# Start Redis
redis-server

# Set environment variables
export AGENT_ROUTER_AGENT_URL="http://localhost:8001"
export AGENT_ROUTER_REDIS_URL="redis://localhost:6379"

# Start the service
agent-router serve --host 0.0.0.0 --port 8000

2. Use the JavaScript Client

# Install the JavaScript client
npm install @agent-router/client

import { createDefaultClient, AgentChat } from '@agent-router/client';

// Create API client
const client = createDefaultClient('http://localhost:8000');

// Use in React app
function App() {
  return (
    <AgentChat
      client={client}
      threadId="my-thread"
      channelType="slack"
    />
  );
}

📋 Repository Structure

agent-router/
├── LICENSE                    # MIT License
├── README.md                  # This file
├── py/                        # Python package
│   ├── agent_router/          # Python source code
│   │   ├── core/             # Core routing and schema
│   │   ├── adapters/         # Channel adapters (Slack, Discord, Email)
│   │   ├── api/              # FastAPI server
│   │   ├── cli.py            # Command-line interface
│   │   └── main.py           # Entry point
│   ├── tests/                # Python tests
│   ├── docs/                 # Technical documentation
│   ├── pyproject.toml        # Python package config
│   └── README.md             # Python package docs
├── js/                       # JavaScript package
│   ├── src/                  # TypeScript source
│   │   ├── index.ts          # Main exports
│   │   ├── apiClient.ts      # REST API client
│   │   ├── AgentChat.tsx     # React chat component
│   │   └── types.ts          # TypeScript definitions
│   ├── dist/                 # Compiled JavaScript
│   ├── package.json          # npm package config
│   ├── tsconfig.json         # TypeScript config
│   └── README.md             # JavaScript package docs
└── shared/                   # Shared schemas
    ├── message.schema.json   # JSON Schema for messages
    └── openapi.yaml          # OpenAPI specification

🔌 Supported Channels

Channel	Python Support	JavaScript Support	Features
Slack	✅ Full	✅ API Client	Webhooks, threads, reactions
Discord	✅ Full	✅ API Client	Bot commands, embeds, reactions
Email	✅ Full	✅ API Client	IMAP/SMTP, threading
Web/API	✅ REST API	✅ React Components	Real-time chat UI

🛠️ Development

Python Development

cd py/
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest

JavaScript Development

cd js/
npm install
npm run build
npm test

📖 Documentation

• Python Package: Complete setup guide for the Agent Router service
• JavaScript Package: Client library and React component documentation
• API Reference: OpenAPI specification
• Message Schema: JSON schema for normalized messages

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes in the appropriate package (py/ or js/)
4. Add tests for new functionality
5. Run the test suite
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• FastAPI for the Python web framework
• Redis for reliable message storage
• TypeScript for type-safe JavaScript
• React for the UI components

📧 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email: hello@agent-router.dev

---

Built with ❤️ for the LLM community