Files · Mistral AI Agent Reliability Suite for SMB Customer Support

# Mistral AI Agent Reliability Suite for SMB Customer Support
 
> Keep your Mistral-powered customer support agents resilient to tool failures with automatic circuit breaking, retries, and incident playbooks.
 
A reliability operations suite that wraps Mistral-based support agents with per-tool circuit breakers, idempotent retry middleware to prevent duplicate actions, and automated health checks and incident runbooks orchestrated by Trigger.dev.
 
## Architecture
 
```
User → POST /api/tools → executeTool() → CircuitBreaker → IdempotencyMiddleware → callExternalApi()
         ↘ MistralChat  → toolCalls detected → executeTool() loop → final reply
         ↘ GET /api/health → getCircuitStatuses() + generateHealthChecks() → status report
         ↘ Circuit trip → Trigger.dev job → generateIncidentWorkflows() + generateRunbookArtifacts()
```
 
### REAA packages used
 
| Package | Role |
|---|---|
| `@reaatech/circuit-breaker-agents` | Per-tool circuit breakers isolate failing downstream APIs |
| `@reaatech/idempotency-middleware` | Prevents duplicate side-effect operations |
| `@reaatech/agent-runbook-health-checks` | Generates Kubernetes probe YAML + health check endpoints |
| `@reaatech/agent-runbook-incident` | SEV1-SEV4 incident response workflows + escalation policies |
| `@reaatech/agent-runbook-runbook` | Assembles runbooks from analysis data and exports to markdown |
 
### Third-party packages
 
- `@mistralai/mistralai` — Mistral chat completions SDK
- `@trigger.dev/sdk` — Durable event-driven jobs for circuit-trip handling
- `langfuse` — LLM observability and tracing
- `zod` — Runtime request validation
- `p-retry` / `p-timeout` — Resilience primitives (exponential backoff, timeouts)
- `p-limit` — Concurrency limiting for the orchestrator
 
## Setup
 
```bash
pnpm install
pnpm typecheck
pnpm lint
pnpm test            # vitest run with coverage
pnpm dev             # next dev
```
 
Copy `.env.example` to `.env` and fill in the values:
 
```bash
cp .env.example .env
```
 
Required environment variables:
 
| Variable | Description |
|---|---|
| `MISTRAL_API_KEY` | Mistral AI API key |
| `TRIGGER_API_KEY` | Trigger.dev API key |
| `TRIGGER_PROJECT_ID` | Trigger.dev project ID |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_HOST` | Langfuse API host |
| `CRM_API_URL` | Base URL for the CRM tool API |
| `ORDER_API_URL` | Base URL for the order lookup API |
| `RETURN_PORTAL_URL` | Base URL for the return portal API |
| `REFUND_API_URL` | Base URL for the refund API |
| `FALLBACK_MODEL` | Mistral model ID for degraded mode fallback |
 
### `circuit/trip` Event Payload
 
When a circuit breaker transitions to OPEN state, a Trigger.dev job is triggered with this payload:
 
```json
{
  "breakerName": "crm-lookup",
  "toolName": "crm-lookup",
  "state": "OPEN",
  "failureCount": 5,
  "timestamp": "2026-05-24T12:00:00.000Z"
}
```
 
## API Reference
 
### `GET /api/health`
 
Returns circuit breaker statuses and generated Kubernetes probe configurations.
 
```json
{
  "status": "healthy",
  "circuitBreakers": {
    "crm-lookup": "CLOSED",
    "order-lookup": "CLOSED",
    "return-portal": "CLOSED",
    "refund-process": "CLOSED"
  },
  "kubernetesProbes": "...",
  "endpointImplementation": "...",
  "timestamp": "2026-05-24T..."
}
```
 
### `POST /api/tools`
 
Execute a support tool with optional idempotency key.
 
```bash
curl -X POST http://localhost:3000/api/tools \
  -H "Content-Type: application/json" \
  -d '{"toolName":"crm-lookup","parameters":{"query":"account-42"},"idempotencyKey":"req-123"}'
```
 
**Success response (200):**
```json
{ "result": { ... }, "durationMs": 123 }
```
 
**Circuit open (503):**
```json
{ "error": "circuit_open", "retryAfter": 30 }
```
 
**Validation error (400):**
```json
{ "error": "invalid_request", "details": [...] }
```
 
## Trigger.dev
 
Start the Trigger.dev dev server:
 
```bash
npx trigger.dev dev
```
 
The `circuit/trip` event triggers the trip handler job, which:
 
1. Generates incident workflows via `@reaatech/agent-runbook-incident`
2. Creates escalation policies
3. Applies communication templates
4. Generates a full runbook via `@reaatech/agent-runbook-runbook`
5. Performs a fallback model smoke test
 
## Project layout
 
```
app/
  api/
    health/route.ts     Health check endpoint
    tools/route.ts      Tool execution endpoint
src/
  lib/
    types.ts            Shared types and Zod schemas
    mistral-client.ts   Mistral AI chat client
    tools.ts            Tool wrapping with circuit breaker + idempotency
  services/
    support-orchestrator.ts   Multi-turn conversation orchestrator
  triggers/
    trip-handler.ts     Trigger.dev job for circuit-trip events
  instrumentation.ts    Next.js instrumentation (langfuse init)
tests/                  Vitest suite (mirrors src/)
```
 
## License
 
MIT — see [LICENSE](./LICENSE).