Files · Mistral AI Multi-Agent Handoff for Linear Support Triage

# Mistral AI Multi-Agent Handoff for Linear Support Triage
 
> Route, hand off, and escalate customer support issues in Linear with a Mistral-powered multi-agent system that preserves context across specialist agents.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Architecture
 
```
Linear Webhook → POST /api/linear-webhook
                         ↓
              ┌─────────────────────┐
              │ Signature Validation │  ← verifyLinearSignature()
              └─────────────────────┘
                         ↓
              ┌─────────────────────┐
              │  Webhook Parser      │  ← parseLinearWebhookPayload()
              └─────────────────────┘
                         ↓
              ┌─────────────────────┐
              │   LangGraph Flow     │
              │                     │
              │  classify  ─→  compress │
              │     │                │
              │     ↓                ↓
              │  budget ─→ route ─→ handoff │
              └─────────────────────┘
                         ↓
              ┌─────────────────────┐
              │   Agent Registry     │
              │  Technical Support   │
              │  Billing Agent       │
              │  Account Agent       │
              └─────────────────────┘
```
 
The workflow uses LangGraph's `StateGraph` to orchestrate: issue classification (Mistral), context compression (REAA), budget enforcement, capability-based agent routing (REAA), and handoff execution.
 
## Prerequisites
 
- Node.js 22+
- pnpm 10+
- Mistral AI API key
- Linear account with API key and webhook secret
 
## Setup
 
```bash
# Clone and install
pnpm install
 
# Configure environment
cp .env.example .env
# Edit .env with your Mistral API key, Linear API key, and webhook secret
 
# Run development server
pnpm dev             # next dev on http://localhost:3000
 
# Run tests
pnpm test            # vitest run with coverage
pnpm typecheck       # TypeScript type checking
pnpm lint            # ESLint
```
 
## Testing Webhooks Locally
 
Use [ngrok](https://ngrok.com) to expose your local dev server:
 
```bash
ngrok http 3000
```
 
Then configure the ngrok URL as a webhook destination in your Linear workspace settings.
 
## API Routes
 
| Route | Method | Description |
|---|---|---|
| `/api/linear-webhook` | POST | Receive Linear issue events, classify, route, and hand off |
| `/api/agent-status` | GET | List registered agents and current budget state |
 
## Environment Variables
 
| Variable | Description |
|---|---|
| `MISTRAL_API_KEY` | Mistral AI API key for issue classification |
| `LINEAR_API_KEY` | Linear personal API key for fetching issue details |
| `LINEAR_WEBHOOK_SECRET` | Linear webhook signing secret for payload verification |
 
## Agent Roles
 
| Agent | Skills | Domains |
|---|---|---|
| **Technical Support** | debugging, performance, integration | api, sdk, frontend |
| **Billing Agent** | invoicing, pricing, refunds | billing, subscription |
| **Account Agent** | account-management, onboarding, permissions | account, iam |
 
Issues are classified into one of three categories by Mistral (with keyword-based pre-classification as a fast path), then routed to the best-matching agent via the REAA `CapabilityBasedRouter`.
 
## Project Layout
 
```
app/                  Next.js App Router pages + API routes
src/
  webhooks/           Linear webhook parsing and signature verification
  classify/           Mistral-powered issue classification
  handoff/            Agent registry and capability-based router
  context/            Conversation context compression
  orchestration/      LangGraph state graph, nodes, and entry point
  budget/             Budget enforcement (spend tracking, pricing)
  lib/                Shared types, config, and client setup
tests/                Vitest suite (mirrors src/)
packages/             API references for every dependency
```
 
## Dependencies
 
- **Mistral AI** (`@mistralai/mistralai`) — LLM-powered classification
- **Linear** (`@linear/sdk`) — Issue fetching and webhook events
- **LangGraph** (`@langchain/langgraph`) — Agent orchestration graph
- **REAA Handoff Protocol** (`@reaatech/*`) — Compression, routing, handoff, budget
 
## License
 
MIT — see [LICENSE](./LICENSE).