kai/smart-support
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reconcile README and docs with actual codebase

Browse Source 
README:
- Remove duplicated agent config, safety, security sections (covered by docs)
- Add ux_design_system.md and safety.py to project structure and doc links
- Convert doc links to descriptive table

agent-config-guide.md:
- Replace fictional agents/tools with real ones from agents.yaml
- Remove nonexistent 'admin' permission level (only read/write)
- Fix template names (e-commerce, saas, fintech)
- List all available built-in tools

openapi-import-guide.md:
- Fix /result -> /classifications endpoint
- Fix POST /approve to show no request body
- Remove nonexistent 'admin' access type
- Update response examples to match actual API

demo-script.md:
- Fix agent names (order_agent -> order_lookup)
- Replace fictional refund scenario with real lookup+cancel flow

ARCHITECTURE.md:
- Fix langgraph-supervisor version (v1.1 -> 0.0.12+)

docker-compose.yml:
- Expose postgres on port 5433 for local dev
This commit is contained in:
Yaojia Wang
2026-04-06 13:55:45 +02:00
parent 19fc9f3289
commit be5c84bcff
6 changed files with 142 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
README.md
View File

@@ -45,10 +45,11 @@ User message -> Chat UI -> FastAPI WebSocket -> LangGraph Supervisor -> Speciali
| Component | Technology | | Component | Technology |
|-----------|-----------| |-----------|-----------|
| Backend | Python 3.11+, FastAPI | | Backend | Python 3.11+, FastAPI |
| Agent orchestration | LangGraph v1.1 | | Agent orchestration | LangGraph 0.4+, langgraph-supervisor |
| Session state | PostgreSQL + langgraph-checkpoint-postgres | | Session state | PostgreSQL 16 + langgraph-checkpoint-postgres |
| LLM | Claude Sonnet 4.6 (configurable: OpenAI, Google) | | LLM | Claude Sonnet 4.6 (configurable: OpenAI, Azure OpenAI, Google) |
| Frontend | React 19, TypeScript, Vite | | Frontend | React 19, TypeScript, Vite |
| Testing | pytest (backend), vitest + happy-dom (frontend) |
| Deployment | Docker Compose | | Deployment | Docker Compose |
## Quick Start ## Quick Start
@@ -59,7 +60,11 @@ cd smart-support
# Configure your LLM API key # Configure your LLM API key
cp .env.example .env cp .env.example .env
# Edit .env: set ANTHROPIC_API_KEY (or OPENAI_API_KEY) # 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 # Start all services
docker compose up -d docker compose up -d
@@ -68,6 +73,25 @@ docker compose up -d
open http://localhost open http://localhost
``` ```
### Local Development
```bash
# 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](docs/deployment.md) for production setup, HTTPS, and scaling.
## Project Structure ## Project Structure
``` ```
@@ -77,15 +101,14 @@ smart-support/
│ │ ├── main.py # FastAPI + WebSocket entry point │ │ ├── main.py # FastAPI + WebSocket entry point
│ │ ├── graph.py # LangGraph Supervisor │ │ ├── graph.py # LangGraph Supervisor
│ │ ├── ws_handler.py # WebSocket message dispatch + rate limiting │ │ ├── ws_handler.py # WebSocket message dispatch + rate limiting
│ │ ├── conversation_tracker.py # Conversation lifecycle tracking │ │ ├── safety.py # Confirmation rules + MCP error taxonomy
│ │ ├── agents/ # Agent definitions and tools │ │ ├── agents/ # Agent definitions and tools
│ │ ├── registry.py # YAML agent registry loader │ │ ├── registry.py # YAML agent registry loader
│ │ ├── openapi/ # OpenAPI parser and review API │ │ ├── openapi/ # OpenAPI parser, classifier, and review API
│ │ ├── replay/ # Conversation replay API │ │ ├── replay/ # Conversation replay API
│ │ ├── analytics/ # Analytics queries and API │ │ └── analytics/ # Analytics queries and API
│ │ └── tools/ # Error handling and retry utilities
│ ├── agents.yaml # Agent registry configuration │ ├── agents.yaml # Agent registry configuration
│ ├── fixtures/ # Demo data and sample OpenAPI spec │ ├── templates/ # Vertical industry templates
│ └── tests/ # Unit, integration, and E2E tests │ └── tests/ # Unit, integration, and E2E tests
├── frontend/ ├── frontend/
│ ├── src/ │ ├── src/
@@ -99,29 +122,6 @@ smart-support/
└── .env.example # Environment variable template └── .env.example # Environment variable template
``` ```
## Agent Configuration
```yaml
# agents.yaml
agents:
- name: order_agent
description: "Handles order status, tracking, and cancellations."
permission: write
tools:
- get_order_status
- cancel_order
personality:
tone: friendly
greeting: "I can help with your order. What is the order number?"
escalation_message: "I'm escalating this to a human agent."
- name: general_agent
description: "Answers general questions and FAQs."
permission: read
tools:
- search_faq
```
## API Endpoints ## API Endpoints
| Method | Path | Description | | Method | Path | Description |
@@ -137,42 +137,31 @@ agents:
| PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | Update a classification | | PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | Update a classification |
| POST | `/api/openapi/jobs/{id}/approve` | Approve and generate tools | | POST | `/api/openapi/jobs/{id}/approve` | Approve and generate tools |
## Safety and Confirmation Rules
Destructive-action confirmation is explicit and auditable (see `backend/app/safety.py`):
- **Read actions** execute immediately -- no confirmation required.
- **Write actions** require human-in-the-loop approval via an interrupt gate.
- **OpenAPI-imported endpoints** use the `needs_interrupt` classification flag.
- **Multi-intent handling** is sequential: if a write action is blocked by an interrupt, subsequent actions are paused until the interrupt is resolved or rejected.
- **MCP errors** are classified into `transient` (retryable, up to 3 attempts), `validation` (not retryable), `auth` (not retryable, escalate), and `unknown` (not retryable, log and escalate).
## Security
- **SSRF protection** -- OpenAPI import blocks private IPs and metadata service URLs
- **Input validation** -- messages validated for size (32 KB), content length (10 KB), thread ID format
- **Rate limiting** -- 10 messages per 10 seconds per session
- **Audit trail** -- every tool call logged with agent, params, result, timestamp
- **Permission isolation** -- each agent only accesses its configured tools
- **Interrupt TTL** -- unanswered approval prompts expire after 30 minutes
## Running Tests ## Running Tests
```bash ```bash
# Backend (516 tests, 94% coverage)
cd backend cd backend
pytest --cov=app --cov-report=term-missing pytest --cov=app --cov-report=term-missing
# Frontend (23 tests, vitest + happy-dom)
cd frontend
npm test
``` ```
Coverage is enforced at 80%+. Backend coverage is enforced at 80%+.
## Documentation ## Documentation
- [Architecture](docs/ARCHITECTURE.md) -- System design and component diagram | Document | Description |
- [Development Plan](docs/DEVELOPMENT-PLAN.md) -- Phase breakdown and status |----------|-------------|
- [Agent Config Guide](docs/agent-config-guide.md) -- How to configure agents | [Architecture](docs/ARCHITECTURE.md) | System design, component diagram, data flow, ADRs |
- [OpenAPI Import Guide](docs/openapi-import-guide.md) -- Auto-discovery workflow | [Development Plan](docs/DEVELOPMENT-PLAN.md) | Phase breakdown, task checklists, and status |
- [Deployment Guide](docs/deployment.md) -- Docker and production deployment | [Agent Config Guide](docs/agent-config-guide.md) | agents.yaml format, fields, templates, routing logic |
- [Demo Script](docs/demo-script.md) -- Step-by-step live demo walkthrough | [OpenAPI Import Guide](docs/openapi-import-guide.md) | Auto-discovery workflow, REST API, SSRF protection |
| [Deployment Guide](docs/deployment.md) | Docker, local dev, production, HTTPS, backups, scaling |
| [Demo Script](docs/demo-script.md) | Step-by-step live demo walkthrough (5 scenes) |
| [UX Design System](docs/ux_design_system.md) | Color palette, typography, component patterns, CSS tokens |
## License ## License

2
docker-compose.yml
View File

@@ -5,7 +5,7 @@ services:
POSTGRES_DB: smart_support POSTGRES_DB: smart_support
POSTGRES_USER: smart_support POSTGRES_USER: smart_support
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-dev_password} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-dev_password}
# ports: ["5432:5432"] # Uncomment for local dev DB access only ports: ["5433:5432"] # Local dev: expose on 5433 to match backend/.env
volumes: volumes:
- pgdata:/var/lib/postgresql/data - pgdata:/var/lib/postgresql/data
healthcheck: healthcheck:

2
docs/ARCHITECTURE.md
View File

@@ -63,7 +63,7 @@ Smart Support 通过 MCP 协议连接内部系统,将自动化率提升到 60%+
v v
+--------+--------------------+ +--------+--------------------+
| LangGraph Supervisor | (Agent 编排 + 意图路由) | LangGraph Supervisor | (Agent 编排 + 意图路由)
| langgraph-supervisor v1.1 | | langgraph-supervisor 0.0.12+|
+--------+--------------------+ +--------+--------------------+
| |
+----+----+----+----+ +----+----+----+----+

86
docs/agent-config-guide.md
View File

@@ -9,33 +9,38 @@ specialist with a specific role, permission level, and set of tools it can call.
```yaml ```yaml
agents: agents:
- name: order_agent - name: order_lookup
description: "Handles order status, tracking, and cancellations." description: "Looks up order status and tracking information."
permission: write permission: read
tools: tools:
- get_order_status - get_order_status
- cancel_order - get_tracking_info
personality: personality:
tone: friendly tone: "friendly and informative"
greeting: "I can help with your order. What is your order number?" greeting: "I can help you check your order status!"
escalation_message: "I'm escalating this to a human agent now." escalation_message: "Let me connect you with our support team."
- name: refund_agent - name: order_actions
description: "Processes refund requests." description: "Performs order modifications like cancellations."
permission: write permission: write
tools: tools:
- process_refund - cancel_order
- check_refund_eligibility personality:
personality: tone: "careful and reassuring"
tone: empathetic greeting: "I can help you with order changes."
greeting: "I'm the refund specialist. How can I help?" escalation_message: "I'll connect you with a specialist."
escalation_message: "I need to escalate this refund request."
- name: discount
- name: general_agent description: "Applies discounts and generates coupon codes."
description: "Answers general questions and FAQs." permission: write
tools:
- apply_discount
- generate_coupon
- name: fallback
description: "Handles general questions and unclear requests."
permission: read permission: read
tools: tools:
- search_faq
- fallback_respond - fallback_respond
``` ```
@@ -52,31 +57,38 @@ user messages to the right agent. Be specific.
Controls the interrupt threshold: Controls the interrupt threshold:
- `read` -- no interrupt required. Agent can act immediately. - `read` -- no interrupt required. Agent can act immediately.
- `write` -- requires human approval via interrupt before executing tools. - `write` -- requires human approval via interrupt before executing tools.
- `admin` -- requires human approval and is logged for audit.
### `tools` (required) ### `tools` (required)
List of tool names this agent can use. Tools are registered in the agent factory. List of tool names this agent can use. Tools are registered in `backend/app/agents/`.
Each tool name must match a registered LangChain tool. Each tool name must match a registered LangChain tool.
Available built-in tools:
- `get_order_status` -- look up order details
- `get_tracking_info` -- get shipping/tracking info
- `cancel_order` -- cancel an order (write)
- `apply_discount` -- apply a discount code (write)
- `generate_coupon` -- generate a new coupon (write)
- `fallback_respond` -- generic fallback response
### `personality` (optional) ### `personality` (optional)
Customizes agent behavior: Customizes agent behavior:
- `tone` -- `friendly`, `formal`, `empathetic`, `technical` - `tone` -- free-text description of the agent's communication style
- `greeting` -- Opening message injected at session start. - `greeting` -- opening message injected at session start
- `escalation_message` -- Message sent when the agent escalates. - `escalation_message` -- message sent when the agent escalates
## Built-in Templates ## Built-in Templates
Use `TEMPLATE_NAME` environment variable to load a pre-built agent configuration: Use `TEMPLATE_NAME` environment variable to load a pre-built agent configuration:
| Template | Description | | Template | Filename | Description |
|----------|-------------| |----------|----------|-------------|
| `ecommerce` | Orders, refunds, shipping, product questions | | `e-commerce` | `templates/e-commerce.yaml` | Orders, shipping, discounts |
| `saas` | Account management, billing, technical support | | `saas` | `templates/saas.yaml` | Account management, billing, support |
| `generic` | General-purpose FAQ and escalation | | `fintech` | `templates/fintech.yaml` | Financial services support |
Example: Example:
```bash ```bash
TEMPLATE_NAME=ecommerce uvicorn app.main:app TEMPLATE_NAME=e-commerce uvicorn app.main:app
``` ```
## Adding New Agents ## Adding New Agents
@@ -98,7 +110,7 @@ matches the agent's description.
## Escalation ## Escalation
Any agent can trigger escalation by calling the `escalate` tool. This: Any agent can trigger escalation. This:
1. Sends a webhook notification (if `WEBHOOK_URL` is configured). 1. Sends a webhook notification (if `WEBHOOK_URL` is configured).
2. Marks the conversation with `resolution_type = escalated`. 2. Marks the conversation with `resolution_type = escalated`.
3. Sends the agent's `escalation_message` to the user. 3. Sends the agent's `escalation_message` to the user.

10
docs/demo-script.md
View File

@@ -46,7 +46,7 @@ Navigate to http://localhost in your browser.
1. Open the Chat tab (default). 1. Open the Chat tab (default).
2. Send: **"What is the status of order 12345?"** 2. Send: **"What is the status of order 12345?"**
- Observe the `tool_call` indicator appear in the sidebar (order_agent calling `get_order_status`). - Observe the `tool_call` indicator appear in the sidebar (`order_lookup` calling `get_order_status`).
- The agent responds with order status. - The agent responds with order status.
3. Send: **"Can you cancel that order?"** 3. Send: **"Can you cancel that order?"**
- The system detects a write operation and shows an **Interrupt Prompt**. - The system detects a write operation and shows an **Interrupt Prompt**.
@@ -61,15 +61,15 @@ Key points to highlight:
### Scene 2: Multi-Agent Routing (2 minutes) ### Scene 2: Multi-Agent Routing (2 minutes)
1. Start a new browser tab (new session) or clear session storage. 1. Start a new browser tab (new session) or clear session storage.
2. Send: **"I need to track my order AND request a refund for a previous order"** 2. Send: **"I need to check order 12345 AND cancel order 67890"**
- The supervisor detects two intents: `order_agent` and `refund_agent`. - The supervisor detects two intents: `order_lookup` (read) and `order_actions` (write).
- Both agents run in sequence. - Both agents run in sequence.
- Two interrupt prompts may appear if both operations are write-level. - The cancellation triggers an interrupt prompt for human approval.
Key points to highlight: Key points to highlight:
- Intent classification detecting multiple actions - Intent classification detecting multiple actions
- Automatic routing to appropriate specialist agents - Automatic routing to appropriate specialist agents
- Sequential execution with confirmation gates - Sequential execution with confirmation gates for write operations
### Scene 3: Conversation Replay (2 minutes) ### Scene 3: Conversation Replay (2 minutes)

68
docs/openapi-import-guide.md
View File

@@ -10,7 +10,8 @@ Import a URL, review the AI-classified endpoints, approve, and your agents are l
1. **Import** -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML). 1. **Import** -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML).
2. **Parse** -- The system downloads and parses the spec. 2. **Parse** -- The system downloads and parses the spec.
3. **Classify** -- An LLM classifies each endpoint's: 3. **Classify** -- An LLM classifies each endpoint's:
- `access_type`: `read`, `write`, or `admin` - `access_type`: `read` or `write`
- `needs_interrupt`: whether human approval is required
- `agent_group`: which specialist agent should handle this endpoint - `agent_group`: which specialist agent should handle this endpoint
4. **Review** -- You inspect and edit the classifications in the UI. 4. **Review** -- You inspect and edit the classifications in the UI.
5. **Approve** -- Approved endpoints are registered as tools on the appropriate agents. 5. **Approve** -- Approved endpoints are registered as tools on the appropriate agents.
@@ -19,12 +20,12 @@ Import a URL, review the AI-classified endpoints, approve, and your agents are l
1. Navigate to the **API Review** tab. 1. Navigate to the **API Review** tab.
2. Paste your OpenAPI spec URL into the import form. 2. Paste your OpenAPI spec URL into the import form.
3. Click **Import**. 3. Click **Scan Tools**.
4. Wait for the job to complete (status: `pending` -> `processing` -> `done`). 4. Wait for the job to complete (status: `pending` -> `processing` -> `done`).
5. Review the endpoint table: 5. Review the endpoint cards grouped by agent:
- Edit `access_type` if the AI misclassified sensitivity. - Edit `access_type` (Read Only / Write) if the AI misclassified sensitivity.
- Edit `agent_group` to reassign an endpoint to a different agent. - Edit the agent assignment to reassign an endpoint to a different agent.
6. Click **Approve & Save** when satisfied. 6. Click **Save Configuration** when satisfied.
## Using the REST API ## Using the REST API
@@ -39,11 +40,15 @@ Content-Type: application/json
} }
``` ```
Response: Response (202):
```json ```json
{ {
"success": true, "job_id": "abc123",
"data": { "job_id": "abc123", "status": "pending" } "status": "pending",
"spec_url": "https://api.example.com/openapi.yaml",
"total_endpoints": 0,
"classified_count": 0,
"error_message": null
} }
``` ```
@@ -53,47 +58,52 @@ Response:
GET /api/openapi/jobs/{job_id} GET /api/openapi/jobs/{job_id}
``` ```
### Get job results ### Get classifications
```http ```http
GET /api/openapi/jobs/{job_id}/result GET /api/openapi/jobs/{job_id}/classifications
```
Response: array of classification objects with `index`, `access_type`,
`needs_interrupt`, `agent_group`, `confidence`, `customer_params`, and `endpoint`.
### Update a classification
```http
PUT /api/openapi/jobs/{job_id}/classifications/{index}
Content-Type: application/json
{
"access_type": "write",
"needs_interrupt": true,
"agent_group": "order_actions"
}
``` ```
### Approve job ### Approve job
```http ```http
POST /api/openapi/jobs/{job_id}/approve POST /api/openapi/jobs/{job_id}/approve
Content-Type: application/json
{
"endpoints": [
{
"path": "/orders/{order_id}",
"method": "get",
"access_type": "read",
"agent_group": "order_agent"
}
]
}
``` ```
No request body. Changes the job status to `approved`.
## Access Type Classification ## Access Type Classification
| Access Type | Description | Interrupt Required | | Access Type | Description | Interrupt Required |
|-------------|-------------|-------------------| |-------------|-------------|-------------------|
| `read` | GET operations, no side effects | No | | `read` | GET operations, no side effects | No |
| `write` | POST/PUT/PATCH that modify data | Yes | | `write` | POST/PUT/PATCH/DELETE that modify data | Yes (by default) |
| `admin` | DELETE, bulk operations, sensitive writes | Yes |
The `needs_interrupt` flag can be overridden per-endpoint during review.
## SSRF Protection ## SSRF Protection
All import requests are validated against an allowlist: All import requests are validated:
- Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x) - Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
- Localhost and metadata service URLs are blocked - Localhost and cloud metadata service URLs are blocked
- Only `http://` and `https://` schemes are permitted - Only `http://` and `https://` schemes are permitted
To allow internal URLs (e.g., in development), set `SSRF_ALLOWLIST_HOSTS` in your environment.
## Supported Spec Formats ## Supported Spec Formats
- OpenAPI 3.0.x (JSON or YAML) - OpenAPI 3.0.x (JSON or YAML)