be5c84bcff
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
117 lines
3.0 KiB
Markdown
117 lines
3.0 KiB
Markdown
# 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
|
|
|
|
1. **Import** -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML).
|
|
2. **Parse** -- The system downloads and parses the spec.
|
|
3. **Classify** -- An LLM classifies each endpoint's:
|
|
- `access_type`: `read` or `write`
|
|
- `needs_interrupt`: whether human approval is required
|
|
- `agent_group`: which specialist agent should handle this endpoint
|
|
4. **Review** -- You inspect and edit the classifications in the UI.
|
|
5. **Approve** -- Approved endpoints are registered as tools on the appropriate agents.
|
|
|
|
## Using the UI
|
|
|
|
1. Navigate to the **API Review** tab.
|
|
2. Paste your OpenAPI spec URL into the import form.
|
|
3. Click **Scan Tools**.
|
|
4. Wait for the job to complete (status: `pending` -> `processing` -> `done`).
|
|
5. Review the endpoint cards grouped by agent:
|
|
- Edit `access_type` (Read Only / Write) if the AI misclassified sensitivity.
|
|
- Edit the agent assignment to reassign an endpoint to a different agent.
|
|
6. Click **Save Configuration** when satisfied.
|
|
|
|
## Using the REST API
|
|
|
|
### Submit an import job
|
|
|
|
```http
|
|
POST /api/openapi/import
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"url": "https://api.example.com/openapi.yaml"
|
|
}
|
|
```
|
|
|
|
Response (202):
|
|
```json
|
|
{
|
|
"job_id": "abc123",
|
|
"status": "pending",
|
|
"spec_url": "https://api.example.com/openapi.yaml",
|
|
"total_endpoints": 0,
|
|
"classified_count": 0,
|
|
"error_message": null
|
|
}
|
|
```
|
|
|
|
### Poll job status
|
|
|
|
```http
|
|
GET /api/openapi/jobs/{job_id}
|
|
```
|
|
|
|
### Get classifications
|
|
|
|
```http
|
|
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
|
|
|
|
```http
|
|
POST /api/openapi/jobs/{job_id}/approve
|
|
```
|
|
|
|
No request body. Changes the job status to `approved`.
|
|
|
|
## Access Type Classification
|
|
|
|
| Access Type | Description | Interrupt Required |
|
|
|-------------|-------------|-------------------|
|
|
| `read` | GET operations, no side effects | No |
|
|
| `write` | POST/PUT/PATCH/DELETE that modify data | Yes (by default) |
|
|
|
|
The `needs_interrupt` flag can be overridden per-endpoint during review.
|
|
|
|
## SSRF Protection
|
|
|
|
All import requests are validated:
|
|
- Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
|
|
- Localhost and cloud metadata service URLs are blocked
|
|
- Only `http://` and `https://` schemes are permitted
|
|
|
|
## 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
|