Files · OpenAI Multi-Agent Handoff for E-commerce Order Handling

# OpenAI Multi-Agent Handoff for E-commerce Order Handling
 
> Handle order status, modifications, and cancellations via a Mastra-orchestrated multi-agent system with OpenAI, preventing duplicate refunds and runaway costs.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Architecture
 
Three specialist agents handle e-commerce order support requests:
 
- **Order Status Agent** — Looks up order status and tracking from Stripe
- **Order Modifications Agent** — Modifies shipping address, items, or delivery instructions via Supabase
- **Cancellations & Refunds Agent** — Cancels orders and issues refunds through Stripe with idempotency guarantees
 
The system uses `@reaatech/agent-mesh` for confidence-based intent classification, `@reaatech/agent-handoff` for structured context transfer, `@reaatech/llm-cache` for instant responses to repeated queries, `@reaatech/agent-budget-engine` for per-conversation spending limits, and `@reaatech/idempotency-middleware` to prevent duplicate refunds.
 
## Setup
 
1. Copy `.env.example` to `.env` and fill in the required values:
   - `OPENAI_API_KEY` — from https://platform.openai.com/api-keys
   - `STRIPE_SECRET_KEY` — from https://dashboard.stripe.com/apikeys
   - `SUPABASE_URL` and `SUPABASE_SECRET_KEY` — from your Supabase project dashboard
   - `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL` — from https://cloud.langfuse.com
2. Run `pnpm install`
3. Run `pnpm dev` to start the Next.js development server
 
## API Endpoints
 
### `POST /api/chat`
Accepts `{ conversationId: string, message: string }`. Routes the message through intent classification → budget check → cache lookup → agent execution. Returns `{ reply, agentId, conversationId, spend }`.
 
### `POST /api/refund`
Processes refunds with idempotency protection. Requires `Idempotency-Key` header. Body: `{ orderId: string, amount: number, reason: string }`. Returns `{ success, refundId, status }`.
 
### `GET /api/conversations`
Lists active conversations with spend and budget state. Returns `{ conversations: [...], totals: { totalSpend, activeCount } }`.
 
### `GET /api/conversations/[id]`
Returns a single conversation with full budget state.
 
## Budget Enforcement
 
Each conversation has a spending limit (default $2.00). The budget controller enforces four states:
 
| State | Trigger | Behaviour |
|---|---|---|
| **Active** | Below 80% limit | Normal operation |
| **Warned** | 80–90% limit | Suggests cheaper model |
| **Degraded** | 90–100% limit | Downgrades model |
| **Stopped** | At 100% limit | Blocks new requests |
 
## Running locally
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/
  lib/                Utilities: Supabase, Stripe, cache, budget, observability
  services/           Mastra workflow, specialist agents, pricing, spend store
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).