initial commit

06-Komunikacja/Web Endpoints - OpenAI-compat API.md

@@ -0,0 +1,93 @@
+# Web Endpoints - OpenAI-compat API
+
+#sympozium #komunikacja #web #api
+
+## Koncepcja
+
+Sympozium może eksponować agentów jako **HTTP API** kompatybilne z OpenAI API i MCP protocol.
+
+## Architektura
+
+```
+HTTP Client
+    ↓
+Envoy Gateway → HTTPRoute (per instance)
+    ↓
+Web Proxy Pod (Deployment - server mode):
+  ├── Agent container
+  ├── Web Proxy sidecar:
+  │   ├── POST /v1/chat/completions → tworzy AgentRun (task mode)
+  │   ├── GET /v1/models → listuje dostępne modele
+  │   ├── SSE /sse → MCP streaming
+  │   ├── POST /message → MCP request
+  │   └── Auth: Bearer sk-<hex> API key
+  ├── IPC Bridge
+  └── Skill sidecars
+```
+
+## Aktywacja
+
+Dodanie skillu `web-endpoint` do SympoziumInstance:
+```yaml
+skills:
+  - skillPackRef: web-endpoint
+```
+
+Instance Reconciler automatycznie:
+1. Tworzy AgentRun w trybie server
+2. AgentRun Reconciler tworzy Deployment + Service
+3. Jeśli Gateway dostępny → HTTPRoute
+
+## Endpointy
+
+| Endpoint | Metoda | Opis |
+|----------|--------|------|
+| `/v1/chat/completions` | POST | OpenAI-compatible chat |
+| `/v1/models` | GET | Lista modeli |
+| `/sse` | GET | MCP SSE stream |
+| `/message` | POST | MCP request |
+| `/health` | GET | Health check |
+
+## Auto-generated API key
+
+Controller automatycznie generuje Secret z API key:
+```
+Secret: <instance>-web-endpoint-key
+  Data:
+    api-key: sk-<random-hex>
+```
+
+Użytkownik używa klucza w Bearer auth:
+```bash
+curl -H "Authorization: Bearer sk-abc123" \
+  https://my-agent.sympozium.example.com/v1/chat/completions
+```
+
+## Rate limiting
+
+```yaml
+webEndpoint:
+  rateLimit:
+    requestsPerMinute: 60
+    burstSize: 10
+```
+
+## Per-request AgentRun
+
+Kluczowe: Web proxy sam działa jako Deployment (server mode), ale **każdy przychodzący request tworzy osobny AgentRun w trybie task**:
+
+```
+POST /v1/chat/completions
+    ↓
+Web Proxy → tworzy AgentRun (mode: task, label: source=web-proxy)
+    ↓
+AgentRun → Job → Agent → wynik
+    ↓
+Web Proxy → HTTP Response (blocking lub streaming)
+```
+
+To zachowuje ephemeral model: izolacja, RBAC, cleanup per request.
+
+---
+
+Powiązane: [[Tryb Server vs Task]] | [[SympoziumInstance]] | [[Cykl życia AgentRun]]