Files

Yaojia Wang 0e78e5b06b feat: complete phase 5 -- error hardening, frontend, Docker, demo, docs

Backend:
- ConversationTracker: Protocol + PostgresConversationTracker for lifecycle tracking
- Error handler: ErrorCategory enum, classify_error(), with_retry() exponential backoff
- Wire PostgresAnalyticsRecorder + ConversationTracker into ws_handler
- Rate limiting (10 msg/10s per thread), edge case hardening
- Health endpoint GET /api/health, version 0.5.0
- Demo seed data script + sample OpenAPI spec

Frontend (all new):
- React Router with NavBar (Chat / Replay / Dashboard / Review)
- ReplayListPage + ReplayPage with ReplayTimeline component
- DashboardPage with MetricCard, range selector, zero-state
- ReviewPage for OpenAPI classification review
- ErrorBanner for WebSocket disconnect handling
- API client (api.ts) with typed fetch wrappers

Infrastructure:
- Frontend Dockerfile (multi-stage node -> nginx)
- nginx.conf with SPA routing + API/WS proxy
- docker-compose.yml with frontend service + healthchecks
- .env.example files (root + backend)

Documentation:
- README.md with quick start and architecture
- Agent configuration guide
- OpenAPI import guide
- Deployment guide
- Demo script

48 new tests, 449 total passing, 92.87% coverage

2026-03-31 21:20:06 +02:00

2.6 KiB

Raw Blame History

OpenAPI Auto-Discovery Guide

Overview

Smart Support can automatically generate AI agents from any OpenAPI 3.0 specification. Import a URL, review the AI-classified endpoints, approve, and your agents are live.

How It Works

Import -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML).
Parse -- The system downloads and parses the spec.
Classify -- An LLM classifies each endpoint's:
- access_type: read, write, or admin
- agent_group: which specialist agent should handle this endpoint
Review -- You inspect and edit the classifications in the UI.
Approve -- Approved endpoints are registered as tools on the appropriate agents.

Using the UI

Navigate to the API Review tab.
Paste your OpenAPI spec URL into the import form.
Click Import.
Wait for the job to complete (status: pending -> processing -> done).
Review the endpoint table:
- Edit access_type if the AI misclassified sensitivity.
- Edit agent_group to reassign an endpoint to a different agent.
Click Approve & Save when satisfied.

Using the REST API

Submit an import job

POST /api/openapi/import
Content-Type: application/json

{
  "url": "https://api.example.com/openapi.yaml"
}

Response:

{
  "success": true,
  "data": { "job_id": "abc123", "status": "pending" }
}

Poll job status

GET /api/openapi/jobs/{job_id}

Get job results

GET /api/openapi/jobs/{job_id}/result

Approve job

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"
    }
  ]
}

Access Type Classification

Access Type	Description	Interrupt Required
`read`	GET operations, no side effects	No
`write`	POST/PUT/PATCH that modify data	Yes
`admin`	DELETE, bulk operations, sensitive writes	Yes

SSRF Protection

All import requests are validated against an allowlist:

Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
Localhost and metadata service URLs are blocked
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

OpenAPI 3.0.x (JSON or YAML)
Swagger 2.0 is not supported

Limitations

Maximum spec file size: 1 MB
Maximum endpoints per spec: 200
Specs requiring authentication headers are not yet supported for import

2.6 KiB Raw Blame History