Files

Yaojia Wang be5c84bcff docs: reconcile README and docs with actual codebase

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

2026-04-06 13:55:45 +02:00

3.0 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 or write
- needs_interrupt: whether human approval is required
- 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 Scan Tools.
Wait for the job to complete (status: pending -> processing -> done).
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.
Click Save Configuration 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 (202):

{
  "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

GET /api/openapi/jobs/{job_id}

Get classifications

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

PUT /api/openapi/jobs/{job_id}/classifications/{index}
Content-Type: application/json

{
  "access_type": "write",
  "needs_interrupt": true,
  "agent_group": "order_actions"
}

Approve job

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

3.0 KiB Raw Blame History