Files · xAI Grok Agent Mesh for Small Business Customer Support
71 (1 binary, 743.0 kB total)attempt 1
README.md·8670 B·markdown
markdown
# xAI Grok Agent Mesh for Small Business Customer Support
> A mesh of AI agents handles billing, tech support, and account inquiries — routing each customer message to the right specialist using the Grok model.
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
## The Problem
Small businesses receive customer inquiries across billing, tech support, and account management — every message needs to reach the right agent quickly. Manually routing messages is slow and error-prone. A single-agent chatbot lacks the depth to handle all three domains well.
**This recipe solves that** by building a multi-agent mesh where each specialist agent (billing, tech support, account services) is powered by xAI's Grok model. An intent classifier routes every customer message to the right specialist automatically, with session continuity across handoffs.
## Architecture
```
┌──────────────┐ ┌──────────────────────────────────────┐
│ Client App │────▶│ POST /api/chat (Next.js) │
└──────────────┘ └──────────┬───────────────────────────┘
│
┌───────────▼───────────┐
│ IncomingRequestSchema │ (Zod validation)
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ Session Manager │ (@reaatech/session-continuity)
│ (getOrCreateSession, │ InMemoryAdapter + SimpleTokenCounter)
│ addMessage, etc.) │
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ Intent Classifier │ (@reaatech/agent-mesh-classifier)
│ (classifierService) │
└───────────┬───────────┘
│
┌─────────────────┼────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Billing │ │ Tech Support │ │ Account Services │
│ Specialist │ │ Specialist │ │ Specialist │
│ (Grok / xAI) │ │ (Grok / xAI) │ │ (Grok / xAI) │
└──────────────┘ └──────────────┘ └──────────────────┘
│ │ │
└─────────────────┼────────────────────┘
│
┌───────────▼───────────┐
│ AgentResponseSchema │ (Zod validation)
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ Session Continuity │ (handoff, endSession)
└───────────────────────┘
```
The flow:
1. Client sends a message via `POST /api/chat`
2. Session service retrieves or creates a session (in-memory storage)
3. Classifier determines the customer's intent (billing, tech-support, or account-services)
4. If confidence is low, a clarification question is returned
5. If a different agent is needed mid-conversation, a handoff is triggered with compressed context
6. The matched specialist agent (powered by Grok via `@ai-sdk/xai`) responds
7. The response is validated and returned; the session ends when the workflow is complete
## Getting Started
```bash
git clone <repo-url>
cd xai-grok-agent-mesh-for-small-business-customer-support
pnpm install
cp .env.example .env
# Edit .env — set XAI_API_KEY to your xAI API key
pnpm dev
```
Test the API:
```bash
curl -X POST http://localhost:3000/api/chat \
-H 'Content-Type: application/json' \
-d '{"sessionId":"test","message":"I was charged twice","userId":"user-1"}'
```
## API Reference
### `POST /api/chat`
Process a customer message through the agent mesh.
**Request body:**
| Field | Type | Required | Description |
|-------------|--------|----------|----------------------------|
| `sessionId` | string | yes | Unique session identifier |
| `message` | string | yes | Customer's message text |
| `userId` | string | yes | Unique user identifier |
**Response body:**
```json
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "test",
"agent_id": "billing",
"response": "I can help resolve that duplicate charge.",
"workflow_complete": true,
"classification": {
"intent": "billing inquiry",
"confidence": 0.92,
"language": "en"
},
"routing": {
"action": "route",
"reason": "dispatched to billing"
},
"duration_ms": 1234
}
```
### `GET /api/chat`
Health check endpoint. Returns `{ status: "healthy", service, timestamp }`.
## Project Structure
```
app/
api/chat/route.ts POST/GET route handler
layout.tsx Root layout
page.tsx Home page
src/
api/gateway-adapter.ts Gateway adapter (health check, cache clear)
lib/
grok-client.ts Grok model client via @ai-sdk/xai
in-memory-adapter.ts In-memory IStorageAdapter implementation
mesh-types.ts Re-exports of @reaatech/agent-mesh types
simple-token-counter.ts Token counter for session budget management
services/
agent-dispatcher.ts Main orchestration (classify → route → dispatch)
agent-registry.ts Agent definitions (billing, tech-support, account-services)
session-service.ts Session lifecycle wrapper around SessionManager
specialist-agents/
billing-agent.ts Billing specialist handler
tech-support-agent.ts Tech support specialist handler
account-services-agent.ts Account services specialist handler
index.ts Re-exports and SPECIALISTS lookup map
index.ts Public API exports
tests/ Vitest test suite (mirrors src/)
packages/ API references for every dependency
DEV_PLAN.md Build plan for this recipe
```
## Package List
| Package | Version | Role |
|---------|---------|------|
| [`@reaatech/agent-mesh`](https://www.npmjs.com/package/@reaatech/agent-mesh) | 1.0.0 | Core domain types and Zod schemas |
| [`@reaatech/agent-mesh-gateway`](https://www.npmjs.com/package/@reaatech/agent-mesh-gateway) | 1.0.0 | Health check and cache clear utilities |
| [`@reaatech/agent-mesh-classifier`](https://www.npmjs.com/package/@reaatech/agent-mesh-classifier) | 1.0.0 | Intent classification service |
| [`@reaatech/agent-mesh-router`](https://www.npmjs.com/package/@reaatech/agent-mesh-router) | 1.0.0 | Turn entry helpers and response formatting |
| [`@reaatech/agent-handoff`](https://www.npmjs.com/package/@reaatech/agent-handoff) | 0.1.0 | Context compression and handoff utilities |
| [`@reaatech/session-continuity`](https://www.npmjs.com/package/@reaatech/session-continuity) | 0.1.0 | Session lifecycle manager with token budget |
| [`@ai-sdk/xai`](https://www.npmjs.com/package/@ai-sdk/xai) | 3.0.96 | xAI Grok provider for the AI SDK |
| [`ai`](https://www.npmjs.com/package/ai) | latest | AI SDK core (generateText) |
| [`next`](https://www.npmjs.com/package/next) | 16.2.9 | Next.js App Router framework |
| [`zod`](https://www.npmjs.com/package/zod) | 4.4.3 | Runtime validation |
## License
MIT — see [LICENSE](./LICENSE).