open-agents-ai 0.184.30 → 0.184.32

package/README.md

@@ -239,6 +239,98 @@ Pipe to `jq`, ingest into monitoring systems, or feed to other agents.
 
 Shows per-process RAM and CPU usage before killing. Detects: cloudflared tunnels, nexus daemons, headless Chrome, TTS servers, Python REPLs, stale OA instances.
 
+### REST API Service (Port 11435)
+
+Open Agents runs a persistent REST API — like Ollama's `/api/` surface but with agentic task execution, OpenAI compatibility, and full TUI command access.
+
+```bash
+oa serve                          # Start on default port 11435
+oa serve --port 9999              # Custom port
+OA_API_KEY=secret oa serve        # Enable Bearer token auth
+```
+
+**Health & Observability:**
+
+```bash
+curl http://localhost:11435/health          # → {"status":"ok","uptime_s":123}
+curl http://localhost:11435/health/ready     # → {"status":"ready","ollama":"reachable"} or 503
+curl http://localhost:11435/version          # → {"version":"0.184.31","node":"v24.14.0","platform":"linux"}
+curl http://localhost:11435/metrics          # → Prometheus text format (request counts, tokens, errors)
+```
+
+**OpenAI-Compatible Inference** (drop-in for any OpenAI client library):
+
+```bash
+# List models (52 models in OpenAI format)
+curl http://localhost:11435/v1/models
+
+# Chat completions (non-streaming)
+curl -X POST http://localhost:11435/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"qwen3.5:9b","messages":[{"role":"user","content":"Hello"}]}'
+# → {"id":"chatcmpl-...","choices":[{"message":{"role":"assistant","content":"Hi there!"}}],"usage":{"prompt_tokens":25,"completion_tokens":5}}
+
+# Chat completions (SSE streaming)
+curl -N -X POST http://localhost:11435/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"qwen3.5:9b","messages":[{"role":"user","content":"Hello"}],"stream":true}'
+# → data: {"choices":[{"delta":{"content":"Hi"}}]}\n\ndata: {"choices":[{"delta":{"content":" there"}}]}\n\n...data: [DONE]
+```
+
+**Agentic Task Execution** (the unique OA capability):
+
+```bash
+# Submit an agentic task
+curl -X POST http://localhost:11435/v1/run \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"fix the null check in auth.ts","model":"qwen3.5:9b","stream":true}'
+
+# List runs
+curl http://localhost:11435/v1/runs
+
+# Abort a run
+curl -X DELETE http://localhost:11435/v1/runs/run-abc123
+```
+
+**Configuration:**
+
+```bash
+curl http://localhost:11435/v1/config              # Get all settings
+curl http://localhost:11435/v1/config/model         # → {"model":"qwen3.5:122b"}
+curl -X PUT http://localhost:11435/v1/config/model \
+  -H "Content-Type: application/json" -d '{"model":"qwen3.5:27b"}'
+curl http://localhost:11435/v1/config/endpoint      # → {"url":"...","backendType":"..."}
+```
+
+**Slash Commands via REST:**
+
+```bash
+curl http://localhost:11435/v1/commands              # List all 100+ commands
+curl -X POST http://localhost:11435/v1/commands/stats  # Execute /stats
+curl -X POST http://localhost:11435/v1/commands/nexus  # Execute /nexus status
+```
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | Liveness check |
+| GET | `/health/ready` | Readiness (probes Ollama) |
+| GET | `/health/startup` | Startup complete |
+| GET | `/version` | OA + Node version |
+| GET | `/metrics` | Prometheus metrics |
+| GET | `/v1/models` | List models (OpenAI format) |
+| POST | `/v1/chat/completions` | Chat inference (OpenAI compatible, streaming + non-streaming) |
+| POST | `/v1/embeddings` | Generate embeddings |
+| POST | `/v1/run` | Submit agentic task |
+| GET | `/v1/runs` | List runs |
+| GET | `/v1/runs/:id` | Run status |
+| DELETE | `/v1/runs/:id` | Abort run |
+| GET | `/v1/config` | All settings |
+| PATCH | `/v1/config` | Update settings |
+| GET/PUT | `/v1/config/model` | Current/switch model |
+| GET/PUT | `/v1/config/endpoint` | Current/switch endpoint |
+| GET | `/v1/commands` | List slash commands |
+| POST | `/v1/commands/:cmd` | Execute command |
+
 ### Enterprise Licensing
 
 Free for non-commercial use under CC-BY-NC-4.0. For enterprise/commercial licensing, contact [zoomerconsulting.com](https://zoomerconsulting.com).