Files · Multi-Agent Handoff Mesh for Small Business Customer Support

# Multi-Agent Handoff Mesh for Small Business Customer Support
 
**Coordinate multiple AI agents with seamless context handoff, budget tracking, and intent routing for a unified customer experience.**
 
## Problem
 
Small businesses often deploy separate AI chatbots for sales, support, and booking, leading to fragmented interactions, lost context, and unpredictable LLM costs when agents overlap. Customers have to repeat themselves, agents work in isolation, and there is no centralized budget control.
 
## Solution
 
This recipe creates a central gateway that classifies incoming messages and routes them to specialized agents. A handoff manager ensures seamless context transfer between agents, while a budget engine tracks spending per agent and across the mesh, preventing budget overruns. The system is provider-agnostic, allowing SMBs to use any LLM backends for different agents.
 
### Architecture
 
```
                    ┌──────────────────┐
                    │     Client       │
                    │ (HTTP / WebSocket)│
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │     Gateway      │
                    │  POST /v1/request │
                    │  (auth, rate-limit)│
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │     Router       │
                    │  resolveAgent()  │
                    │  routeRequest()  │
                    └───┬─────────┬────┘
                        │         │
              ┌─────────▼──┐  ┌──▼──────────┐
              │ Budget     │  │  Handoff    │
              │ Controller │  │  Manager    │
              │ (spend     │  │ (context    │
              │  tracking) │  │  transfer)  │
              └─────────┬──┘  └──┬──────────┘
                        │         │
              ┌─────────▼─────────▼──────────┐
              │      Specialized Agents      │
              │  (Sales / Support / Booking) │
              └──────────────────────────────┘
```
 
## Prerequisites
 
- Node.js >= 22
- pnpm >= 10
 
## Installation
 
```bash
git clone <repo>
cp .env.example .env
# Fill in your API_KEY and other values
pnpm install
```
 
## Development
 
```bash
pnpm run dev        # Start development server with hot-reload
pnpm run build      # Compile TypeScript to dist/
pnpm start          # Start production server
```
 
### Sample Request
 
```bash
curl -X POST http://localhost:3000/api/v1/request \
  -H "x-api-key: dev-key" \
  -H "Content-Type: application/json" \
  -d '{"input":"I need help with my order","user_id":"user-1"}'
```
 
## API Reference
 
### POST /api/v1/request
 
**Request body:**
```json
{
  "input": "string (required)",
  "employee_id": "string (optional)",
  "user_id": "string (required)",
  "session_id": "string (optional)"
}
```
 
**Response (200):**
```json
{
  "request_id": "string",
  "session_id": "string",
  "agent_id": "string",
  "response": "string",
  "workflow_complete": false,
  "classification": {
    "intent": "string",
    "confidence": 0.95,
    "language": "en"
  },
  "routing": {
    "action": "route | clarify | fallback",
    "reason": "string"
  },
  "duration_ms": 120
}
```
 
## WebSocket Endpoint
 
Connect at `ws://localhost:3000?api_key=***&sessionId=...`
 
### Event Protocol
 
| Direction  | Type          | Description                     |
|-----------|---------------|---------------------------------|
| Server    | `connected`   | Welcome event with sessionId    |
| Client    | (JSON)        | `{ type, input?, sessionId? }`  |
| Server    | `processing`  | Request accepted and processing |
| Server    | `result`      | Final response payload          |
| Server    | `error`       | Error message                   |
| Server    | `shutdown`    | Server shutting down            |
 
## Configuration
 
| Variable                    | Default        | Description                               |
|----------------------------|----------------|-------------------------------------------|
| `PORT`                     | `3000`         | HTTP server port                          |
| `API_KEY`                  | (required)     | API key for authentication                |
| `AGENT_REGISTRY_DIR`       | `./agents`     | Directory with agent YAML configs         |
| `SPEND_STORE_PATH`         | `./spend.json` | Path to persist spend tracking data       |
| `RATE_LIMIT_WINDOW_MS`     | `900000`       | Rate limit window (15 min)                |
| `RATE_LIMIT_MAX_REQUESTS`  | `100`          | Max requests per window                   |
| `MCP_REQUEST_TIMEOUT_MS`   | `30000`        | MCP dispatch timeout                      |
| `MCP_MAX_RETRIES`          | `3`            | Max retries for MCP dispatch              |
 
## Testing
 
```bash
pnpm test             # Run tests
pnpm run test:coverage # Run tests with coverage report
```
 
## License
 
MIT