Smart Support

AI customer support action layer. Paste your API spec, get an AI agent that executes real actions.

The Problem

Existing support tools (Zendesk, Intercom, Ada) answer FAQs well but automation rates stall at 20-30%. The remaining 70% of tickets require agents to manually log into internal systems to look up orders, cancel orders, issue coupons.

Smart Support fills that gap as the "action layer" -- it does not replace your existing support platform, it enables AI to directly call your internal systems.

How It Works

User message -> Chat UI -> FastAPI WebSocket -> LangGraph Supervisor -> Specialist Agent -> MCP Tools -> Your systems
                                                        |                      |
                                                  Agent Registry          interrupt()
                                                  (YAML config)         (human approval)
                                                        |
                                                  PostgresSaver
                                               (session persistence)

1. User sends a message in the chat UI.
2. LangGraph Supervisor classifies intent and routes to the right agent.
3. Agent calls your internal systems via MCP tools.
4. Write operations trigger a human-in-the-loop approval gate.
5. All operations are logged with full replay and analytics.

Key Features

• Multi-agent routing -- each operation goes to a specialist agent with its own tools and permissions
• Zero-config import -- paste an OpenAPI 3.0 URL, agents are generated automatically
• Human-in-the-loop -- all write operations (cancel, refund, modify) require approval; reads execute immediately
• Session context -- multi-turn conversation with persistent state across reconnects
• Real-time streaming -- WebSocket token streaming with live tool call visibility
• Conversation replay -- step-by-step audit trail of every agent decision
• Analytics dashboard -- resolution rate, agent usage, escalation rate, cost per conversation
• YAML-driven config -- agents, personas, and vertical templates in a single file

Tech Stack

Component	Technology
Backend	Python 3.11+, FastAPI
Agent orchestration	LangGraph 1.x, langgraph-supervisor
Session state	PostgreSQL 16 + langgraph-checkpoint-postgres
LLM	Claude Sonnet 4.6 (configurable: OpenAI, Azure OpenAI, Google)
Frontend	React 19, TypeScript, Vite
Testing	pytest (backend), vitest + happy-dom (frontend)
Deployment	Docker Compose

Quick Start

git clone <repo-url>
cd smart-support

# Configure your LLM API key
cp .env.example .env
# Edit .env: set LLM_PROVIDER and the corresponding API key
#   anthropic    -> ANTHROPIC_API_KEY
#   openai       -> OPENAI_API_KEY
#   azure_openai -> AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT + AZURE_OPENAI_DEPLOYMENT
#   google       -> GOOGLE_API_KEY

# Start all services
docker compose up -d

# Open the app
open http://localhost

Local Development

# Start only PostgreSQL via Docker (exposed on port 5433)
docker compose up postgres -d

# Backend (in one terminal)
cd backend
pip install -e ".[dev]"
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

# Frontend (in another terminal)
cd frontend
npm install
npm run dev    # http://localhost:5173 (proxies /api and /ws to :8001)

See Deployment Guide for production setup, HTTPS, and scaling.

Project Structure

smart-support/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI + WebSocket entry point
│   │   ├── graph.py             # LangGraph Supervisor construction
│   │   ├── graph_context.py     # Typed wrapper for graph + classifier + registry
│   │   ├── ws_handler.py        # WebSocket message dispatch + rate limiting
│   │   ├── ws_context.py        # WebSocket dependency bundle
│   │   ├── auth.py              # API key authentication middleware
│   │   ├── api_utils.py         # Shared API response helpers
│   │   ├── safety.py            # Confirmation rules + MCP error taxonomy
│   │   ├── agents/              # Agent definitions and tools
│   │   ├── registry.py          # YAML agent registry loader
│   │   ├── openapi/             # OpenAPI parser, classifier, and review API
│   │   ├── replay/              # Conversation replay API
│   │   └── analytics/           # Analytics queries and API
│   ├── agents.yaml              # Agent registry configuration
│   ├── templates/               # Vertical industry templates
│   └── tests/                   # Unit, integration, and E2E tests
├── frontend/
│   ├── src/
│   │   ├── pages/               # Chat, Replay, Dashboard, Review pages
│   │   ├── components/          # NavBar, Layout, MetricCard, ReplayTimeline
│   │   ├── hooks/               # useWebSocket with reconnect support
│   │   └── api.ts               # Typed API client
│   └── Dockerfile               # Multi-stage nginx build
├── docs/                        # Architecture, deployment, guides
├── docker-compose.yml           # Full-stack compose
└── .env.example                 # Environment variable template

API Endpoints

Method	Path	Auth	Description
WS	/ws	Token	Main WebSocket chat endpoint (?token=<key>)
GET	/api/health	No	Health check
GET	/api/conversations	API Key	List conversations (paginated)
GET	/api/replay/{thread_id}	API Key	Replay conversation steps (paginated)
GET	/api/analytics	API Key	Analytics summary (?range=7d)
POST	/api/openapi/import	API Key	Start OpenAPI import job
GET	/api/openapi/jobs/{id}	API Key	Check import job status
GET	/api/openapi/jobs/{id}/classifications	API Key	Get endpoint classifications
PUT	/api/openapi/jobs/{id}/classifications/{idx}	API Key	Update a classification
POST	/api/openapi/jobs/{id}/approve	API Key	Approve and generate tools

Authentication is controlled by the ADMIN_API_KEY environment variable. API Key endpoints require the X-API-Key header. When ADMIN_API_KEY is unset, auth is disabled.

Running Tests

# Backend (516 tests, 94% coverage)
cd backend
pytest --cov=app --cov-report=term-missing

# Frontend (23 tests, vitest + happy-dom)
cd frontend
npm test

Backend coverage is enforced at 80%+.

Documentation

Document	Description
Architecture	System design, component diagram, data flow, ADRs
Development Plan	Phase breakdown, task checklists, and status
Agent Config Guide	agents.yaml format, fields, templates, routing logic
OpenAPI Import Guide	Auto-discovery workflow, REST API, SSRF protection
Deployment Guide	Docker, local dev, production, HTTPS, backups, scaling
Demo Script	Step-by-step live demo walkthrough (5 scenes)
UX Design System	Color palette, typography, component patterns, CSS tokens

License

MIT