mirror of https://github.com/aliasrobotics/cai.git
Add API capabilities in PRO to docs
Signed-off-by: Víctor Mayoral Vilches <v.mayoralv@gmail.com>
This commit is contained in:
Víctor Mayoral Vilches
parent
d6e8b0d561
commit
43ecefcdff
|
|
@ -0,0 +1,669 @@
|
||||||
|
# CAI API Backend
|
||||||
|
|
||||||
|
The `cai --api` mode exposes a stateful HTTP backend built with FastAPI. It uses per-session agents to keep conversation state and REST routes to run REPL commands or send prompts to the model.
|
||||||
|
|
||||||
|
## Start the server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cai --api --api-host 0.0.0.0 --api-port 8080
|
||||||
|
# If 8080 (or your chosen port) is busy, the server auto-picks
|
||||||
|
# the next free port and prints it in the console.
|
||||||
|
```
|
||||||
|
|
||||||
|
CLI flags and environment variables:
|
||||||
|
|
||||||
|
| Flag | Env | Description |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `--api` | `CAI_API_MODE` | Enable the HTTP backend. |
|
||||||
|
| `--api-host` | `CAI_API_HOST` | Bind host/interface (default 127.0.0.1). |
|
||||||
|
| `--api-port` | `CAI_API_PORT` | Bind port (default 8000). |
|
||||||
|
| `--api-reload` | `CAI_API_RELOAD` | Dev autoreload. |
|
||||||
|
| `--api-workers` | `CAI_API_WORKERS` | Worker processes (ignored with reload). |
|
||||||
|
|
||||||
|
Interactive docs at `/api/docs` and OpenAPI spec at `/api/openapi.json`.
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
- The API uses the client’s `ALIAS_API_KEY` as the secret. Set `ALIAS_API_KEY` and send it in header `X-CAI-API-Key` (customizable via `CAI_API_KEY_HEADER`).
|
||||||
|
- If `ALIAS_API_KEY` is not set, the API is unprotected (local dev only). For compatibility, `CAI_API_KEY` is accepted as a fallback.
|
||||||
|
|
||||||
|
Verbose/auth logging
|
||||||
|
- Server logs level: set `CAI_API_LOG_LEVEL` to `debug` (or `trace`) before `cai --api`.
|
||||||
|
- Request logging (method/path/headers/body preview): `CAI_API_LOG_REQUESTS=true`.
|
||||||
|
- Authentication decisions (why 401): `CAI_API_LOG_AUTH=true`.
|
||||||
|
- Dev autoreload: `CAI_API_RELOAD=true`.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
```bash
|
||||||
|
ALIAS_API_KEY="your_key" \
|
||||||
|
CAI_API_LOG_LEVEL=debug \
|
||||||
|
CAI_API_LOG_REQUESTS=true \
|
||||||
|
CAI_API_LOG_AUTH=true \
|
||||||
|
CAI_API_RELOAD=true \
|
||||||
|
cai --api --api-host 0.0.0.0 --api-port 8080
|
||||||
|
```
|
||||||
|
|
||||||
|
### Content types
|
||||||
|
|
||||||
|
- JSON for request/response payloads.
|
||||||
|
- Server-Sent Events (SSE) for streaming endpoint (`text/event-stream`).
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
Below are the endpoints with request/response examples and headers. For authenticated calls, include:
|
||||||
|
|
||||||
|
- `X-CAI-API-Key: $ALIAS_API_KEY`
|
||||||
|
|
||||||
|
Quick index
|
||||||
|
- GET /api/v1/health
|
||||||
|
- GET /api/v1/commands
|
||||||
|
- POST /api/v1/commands/{command}
|
||||||
|
- POST /api/v1/sessions
|
||||||
|
- GET /api/v1/sessions
|
||||||
|
- GET /api/v1/sessions/{id}
|
||||||
|
- DELETE /api/v1/sessions/{id}
|
||||||
|
- POST /api/v1/sessions/{id}/reset
|
||||||
|
- POST /api/v1/sessions/{id}/messages
|
||||||
|
- POST /api/v1/sessions/{id}/messages/stream
|
||||||
|
- GET /api/v1/sessions/{id}/history
|
||||||
|
- POST /api/v1/sessions/{id}/interrupt
|
||||||
|
- POST /api/v1/sessions/{id}/reload
|
||||||
|
- GET /api/v1/agents
|
||||||
|
- GET /api/v1/models
|
||||||
|
- POST /api/v1/sessions/{id}/ux/final_message/stream_tokens
|
||||||
|
- POST /api/v1/ux/title
|
||||||
|
- POST /api/v1/ux/summarize
|
||||||
|
|
||||||
|
### GET /api/v1/health
|
||||||
|
- Description: Liveness check. No auth required.
|
||||||
|
- Response 200:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"status":"ok","version":"<semver or dev>"}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /api/v1/commands
|
||||||
|
- Description: List all REPL commands (names, aliases, subcommands).
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
- Response 200:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"commands": [
|
||||||
|
{"name":"/memory","description":"memory ops","aliases":[],"subcommands":["show"]},
|
||||||
|
{"name":"/help","description":"display help","aliases":["/h"],"subcommands":[]}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /api/v1/commands/{command}
|
||||||
|
- Description: Execute a REPL command.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`
|
||||||
|
- Body:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"args": ["show"], "auto_correct": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Response 200:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"handled": true, "suggested_command": null, "stdout": "...", "stderr": "", "exit_code": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /api/v1/sessions
|
||||||
|
- Description: Create a new stateful session with its own agent instance and memory.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`
|
||||||
|
- Body:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"agent": "redteam_agent", "model": "alias1", "stateful": true, "metadata": {}}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Response 201 (SessionDetailModel): includes summary + empty history initially.
|
||||||
|
|
||||||
|
### GET /api/v1/sessions
|
||||||
|
- Description: List active sessions (summaries).
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
- Response 200:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"sessions": [{"id":"<uuid>","agent":"redteam_agent","model":"alias1","stateful":true,"history_length":0, "created_at":"...","updated_at":"...","metadata":{}}]}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /api/v1/sessions/{id}
|
||||||
|
- Description: Get session detail (summary + full history).
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
|
||||||
|
### DELETE /api/v1/sessions/{id}
|
||||||
|
- Description: Delete a session.
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
- Response: 204 No Content
|
||||||
|
|
||||||
|
### POST /api/v1/sessions/{id}/reset
|
||||||
|
- Description: Reset the session agent and clear history.
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
- Response 200: SessionDetailModel
|
||||||
|
|
||||||
|
### POST /api/v1/sessions/{id}/messages
|
||||||
|
- Description: Non-streamed inference. Runs the agent and returns the final result.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`
|
||||||
|
- Body (InferenceRequest):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"input": "List current risks", "context": {"org": "acme"}, "max_turns": 8}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Response 200 (InferenceResponse):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"session": {"id": "<uuid>", ...},
|
||||||
|
"result": {
|
||||||
|
"messages": [/* semantic items: messages, tool calls, outputs, ... */],
|
||||||
|
"history": [/* updated message list */],
|
||||||
|
"final_output": {/* typed final output if agent uses an output schema, else string */},
|
||||||
|
"text_output": "<assistant final text, if any>",
|
||||||
|
"input_guardrails": [],
|
||||||
|
"output_guardrails": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /api/v1/sessions/{id}/messages/stream (SSE)
|
||||||
|
- Description: Stream high-level reasoning steps live (no token streaming) and a final summary. Under the hood the API performs non-streaming model calls and streams steps via server-side hooks (tools, handoffs, messages).
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`, `Accept: text/event-stream`
|
||||||
|
- Body (InferenceRequest): same as non-streamed.
|
||||||
|
- Stream format: Server-Sent Events with two event types:
|
||||||
|
- `event: reasoning_step` — One event per step with JSON `data` (examples below).
|
||||||
|
- `event: final` — Final event with `{ steps, final_message, final_output }`.
|
||||||
|
|
||||||
|
Reasoning step payloads (no token deltas):
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Message generated by the assistant
|
||||||
|
{"type":"message","agent":"Red Team","text":"...full assistant message..."}
|
||||||
|
|
||||||
|
// Tool call
|
||||||
|
{"type":"tool_call","agent":"Red Team","tool":"nmap_scan","arguments":{"target":"10.0.0.5"}}
|
||||||
|
|
||||||
|
// Tool output
|
||||||
|
{"type":"tool_output","agent":"Red Team","output":"open ports: 22,80"}
|
||||||
|
|
||||||
|
// Agent switch (handoff)
|
||||||
|
{"type":"handoff","from_agent":"Coordinator","to_agent":"Exploiter"}
|
||||||
|
|
||||||
|
// Explicit agent switch signal
|
||||||
|
{"type":"agent_switched","agent":"Exploiter"}
|
||||||
|
```
|
||||||
|
|
||||||
|
Final event payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"steps": [ /* the same reasoning steps emitted during the stream */ ],
|
||||||
|
"final_message": "...last assistant message (if any)...",
|
||||||
|
"final_output": {/* structured output if present, else string/null */}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Example with curl (SSE):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -N \
|
||||||
|
-H "Accept: text/event-stream" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
-d '{"input": "List current risks"}' \
|
||||||
|
http://localhost:8080/api/v1/sessions/<SESSION_ID>/messages/stream
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /api/v1/sessions/{id}/messages/stream_tokens (SSE)
|
||||||
|
- Description: Token-level streaming (plus reasoning steps). This endpoint enables provider streaming internally and emits token deltas as they arrive. Use this only if you need character/token granularity.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`, `Accept: text/event-stream`
|
||||||
|
- Body (InferenceRequest): same as non-streamed.
|
||||||
|
- Stream events:
|
||||||
|
- `event: token` with data `{ "type": "token_delta", "text": "..." }` for each emitted text delta.
|
||||||
|
- `event: token` with data `{ "type": "message_start" }` and `{ "type": "message_end" }` to mark boundaries.
|
||||||
|
- `event: reasoning_step` for high-level steps (same schema as /messages/stream).
|
||||||
|
- `event: final` with the same summary payload as /messages/stream.
|
||||||
|
|
||||||
|
Notes
|
||||||
|
- Token streaming can be quite chatty; ensure your client handles backpressure and uses streaming-friendly APIs.
|
||||||
|
- For iOS, prefer URLSession streaming (see sample below); Safari’s EventSource cannot set custom headers.
|
||||||
|
|
||||||
|
curl example (tokens):
|
||||||
|
```bash
|
||||||
|
curl -N \
|
||||||
|
-H "Accept: text/event-stream" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
-d '{"input": "Write a haiku about ports"}' \
|
||||||
|
http://localhost:8080/api/v1/sessions/<SESSION_ID>/messages/stream_tokens
|
||||||
|
```
|
||||||
|
|
||||||
|
iOS (Swift) streaming example (tokens)
|
||||||
|
```swift
|
||||||
|
let sid = "<SESSION_ID>"
|
||||||
|
var req = URLRequest(url: URL(string: "http://127.0.0.1:8080/api/v1/sessions/\(sid)/messages/stream_tokens")!)
|
||||||
|
req.httpMethod = "POST"
|
||||||
|
req.addValue("text/event-stream", forHTTPHeaderField: "Accept")
|
||||||
|
req.addValue("application/json", forHTTPHeaderField: "Content-Type")
|
||||||
|
req.addValue(ProcessInfo.processInfo.environment["ALIAS_API_KEY"] ?? "", forHTTPHeaderField: "X-CAI-API-Key")
|
||||||
|
req.httpBody = try! JSONSerialization.data(withJSONObject: ["input": "Hi"], options: [])
|
||||||
|
|
||||||
|
let task = URLSession.shared.streamTask(with: req)
|
||||||
|
task.resume()
|
||||||
|
task.readData(ofMinLength: 1, maxLength: 8192, timeout: 0) { data, atEOF, error in
|
||||||
|
if let data = data, let s = String(data: data, encoding: .utf8) {
|
||||||
|
// parse SSE lines: event: <name> / data: <json>
|
||||||
|
print(s)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Implementation notes (for curious devs)
|
||||||
|
- API streaming never enables OpenAI chat completions token streaming. Instead:
|
||||||
|
- We run the agent with non-streaming model calls and emit events via RunHooks (tools start/end, handoffs, agent switches).
|
||||||
|
- We add one message step after each assistant turn (full text, no token deltas).
|
||||||
|
- This guarantees that model streaming is always off while still providing live step updates.
|
||||||
|
|
||||||
|
## Schemas (request/response fields)
|
||||||
|
|
||||||
|
- HealthResponse
|
||||||
|
- status: string
|
||||||
|
- version: string
|
||||||
|
|
||||||
|
- CommandMetadata
|
||||||
|
- name: string (e.g., "/memory")
|
||||||
|
- description: string
|
||||||
|
- aliases: string[] (e.g., ["/h"])
|
||||||
|
- subcommands: string[] (e.g., ["show"])
|
||||||
|
|
||||||
|
- CommandsResponse
|
||||||
|
- commands: CommandMetadata[]
|
||||||
|
|
||||||
|
- CommandRequest
|
||||||
|
- args: string[] (optional)
|
||||||
|
- auto_correct: boolean (default true)
|
||||||
|
|
||||||
|
- CommandResponse
|
||||||
|
- handled: boolean
|
||||||
|
- suggested_command: string | null
|
||||||
|
- stdout: string
|
||||||
|
- stderr: string
|
||||||
|
- exit_code: number | null
|
||||||
|
|
||||||
|
- CreateSessionRequest
|
||||||
|
- agent: string (optional; default from CAI_AGENT_TYPE)
|
||||||
|
- model: string (optional; default from CAI_MODEL)
|
||||||
|
- stateful: boolean (default true)
|
||||||
|
- metadata: object (optional)
|
||||||
|
|
||||||
|
- SessionSummary
|
||||||
|
- id: string (UUID)
|
||||||
|
- agent: string
|
||||||
|
- model: string
|
||||||
|
- stateful: boolean
|
||||||
|
- created_at: ISO8601 string
|
||||||
|
- updated_at: ISO8601 string
|
||||||
|
- history_length: number
|
||||||
|
- metadata: object
|
||||||
|
|
||||||
|
- SessionDetail
|
||||||
|
- All SessionSummary fields, plus:
|
||||||
|
- history: ResponseInputItem[] (OpenAI Responses input items list – user/system/assistant/tool items)
|
||||||
|
|
||||||
|
- SessionsResponse
|
||||||
|
- sessions: SessionSummary[]
|
||||||
|
|
||||||
|
- InferenceRequest
|
||||||
|
- input: string | ResponseInputItem[]
|
||||||
|
- context: object (optional)
|
||||||
|
- max_turns: number (optional)
|
||||||
|
|
||||||
|
- RunResultPayload
|
||||||
|
- messages: Item[] (list of semantic items generated during the run; see below)
|
||||||
|
- history: ResponseInputItem[] (original input plus generated items, suitable to continue)
|
||||||
|
- final_output: any (typed result if the agent defines an output schema; otherwise text or null)
|
||||||
|
- text_output: string | null (last assistant text message, if any)
|
||||||
|
- input_guardrails: object[] (guardrail outputs for input)
|
||||||
|
- output_guardrails: object[] (guardrail outputs for final output)
|
||||||
|
|
||||||
|
### Item: messages[] entry (non-streamed endpoint)
|
||||||
|
- Common envelope:
|
||||||
|
- type: string (e.g., "message_output_item", "tool_call_item", "tool_call_output_item", "handoff_output_item")
|
||||||
|
- agent: string | null (agent name that produced it)
|
||||||
|
- payload: object (raw Pydantic model dump for the underlying output/input item)
|
||||||
|
- output: any (only present for tool_call_output_item; the structured tool return value)
|
||||||
|
|
||||||
|
- message_output_item
|
||||||
|
- payload: ResponseOutputMessage (OpenAI Responses message with content array)
|
||||||
|
- text extraction: text_output consolidates last text chunk
|
||||||
|
|
||||||
|
- tool_call_item
|
||||||
|
- payload: ResponseFunctionToolCall | ResponseComputerToolCall | ResponseFileSearchToolCall
|
||||||
|
- typical fields (function call): name, arguments
|
||||||
|
|
||||||
|
- tool_call_output_item
|
||||||
|
- output: any (decoded tool result)
|
||||||
|
|
||||||
|
- handoff_output_item
|
||||||
|
- payload: handoff input item
|
||||||
|
- Includes implicit source/target agent names in the envelope (agent + payload content)
|
||||||
|
|
||||||
|
### Streaming events (reasoning_step)
|
||||||
|
- Emitted from /messages/stream; one SSE per step.
|
||||||
|
- step.type values and fields:
|
||||||
|
- message
|
||||||
|
- agent: string | null
|
||||||
|
- text: string (full assistant message; no token deltas)
|
||||||
|
- tool_call
|
||||||
|
- agent: string | null
|
||||||
|
- tool: string (tool/function name)
|
||||||
|
- arguments: object | string (as available)
|
||||||
|
- tool_output
|
||||||
|
- agent: string | null
|
||||||
|
- output: any (structured tool output)
|
||||||
|
- handoff
|
||||||
|
- from_agent: string | null
|
||||||
|
- to_agent: string | null
|
||||||
|
- agent_switched
|
||||||
|
- agent: string | null (new active agent)
|
||||||
|
|
||||||
|
Final event (event: final)
|
||||||
|
- steps: the array of emitted reasoning_step payloads
|
||||||
|
- final_message: string | null
|
||||||
|
- final_output: any
|
||||||
|
|
||||||
|
## Errors and status codes
|
||||||
|
- 401 Unauthorized — missing/invalid `X-CAI-API-Key` when auth is enabled
|
||||||
|
- {"detail":"Invalid or missing API key"}
|
||||||
|
- 404 Not Found — e.g., unknown session id
|
||||||
|
- {"detail":"Session not found"}
|
||||||
|
- 422 Unprocessable Entity — malformed request body
|
||||||
|
- Standard FastAPI validation error
|
||||||
|
- 500 Internal Server Error — unexpected agent execution failure
|
||||||
|
- {"detail":"Agent execution failed: ..."}
|
||||||
|
|
||||||
|
## Building a client (quick recipes)
|
||||||
|
|
||||||
|
Python (requests; SSE via iter_lines)
|
||||||
|
```python
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import requests
|
||||||
|
|
||||||
|
BASE = "http://127.0.0.1:8080/api/v1"
|
||||||
|
HEADERS = {"X-CAI-API-Key": os.environ.get("ALIAS_API_KEY", ""), "Content-Type": "application/json"}
|
||||||
|
|
||||||
|
# 1) Create session
|
||||||
|
sess = requests.post(f"{BASE}/sessions", headers=HEADERS, json={"agent":"redteam_agent","model":"alias1","stateful":True}).json()
|
||||||
|
sid = sess["id"]
|
||||||
|
|
||||||
|
# 2) Non-streamed
|
||||||
|
res = requests.post(f"{BASE}/sessions/{sid}/messages", headers=HEADERS, json={"input":"List current risks"}).json()
|
||||||
|
print(res["result"]["text_output"]) # final message
|
||||||
|
|
||||||
|
# 3) Streaming (SSE)
|
||||||
|
stream_headers = HEADERS | {"Accept": "text/event-stream"}
|
||||||
|
with requests.post(f"{BASE}/sessions/{sid}/messages/stream", headers=stream_headers, json={"input":"List current risks"}, stream=True) as r:
|
||||||
|
for line in r.iter_lines(decode_unicode=True):
|
||||||
|
if not line:
|
||||||
|
continue
|
||||||
|
if line.startswith("event:"):
|
||||||
|
evt = line.split(":", 1)[1].strip()
|
||||||
|
elif line.startswith("data:"):
|
||||||
|
data = json.loads(line.split(":", 1)[1].strip())
|
||||||
|
if evt == "reasoning_step":
|
||||||
|
print("step:", data)
|
||||||
|
elif evt == "final":
|
||||||
|
print("final:", data)
|
||||||
|
```
|
||||||
|
|
||||||
|
Node (browser/EventSource)
|
||||||
|
```js
|
||||||
|
const key = process.env.ALIAS_API_KEY;
|
||||||
|
const sid = "<SESSION_ID>"; // create via POST /sessions
|
||||||
|
const es = new EventSource(`http://localhost:8080/api/v1/sessions/${sid}/messages/stream`, {
|
||||||
|
withCredentials: false
|
||||||
|
});
|
||||||
|
// Note: To send headers with SSE in the browser, proxy or use fetch+ReadableStream.
|
||||||
|
es.addEventListener('reasoning_step', ev => console.log('step', JSON.parse(ev.data)));
|
||||||
|
es.addEventListener('final', ev => console.log('final', JSON.parse(ev.data)));
|
||||||
|
```
|
||||||
|
|
||||||
|
Node (fetch + ReadableStream; set auth header)
|
||||||
|
```js
|
||||||
|
import fetch from 'node-fetch';
|
||||||
|
const key = process.env.ALIAS_API_KEY;
|
||||||
|
const sid = process.env.SID;
|
||||||
|
const resp = await fetch(`http://localhost:8080/api/v1/sessions/${sid}/messages/stream`, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type':'application/json', 'Accept':'text/event-stream', 'X-CAI-API-Key': key },
|
||||||
|
body: JSON.stringify({ input: 'List current risks' })
|
||||||
|
});
|
||||||
|
for await (const chunk of resp.body) {
|
||||||
|
const s = chunk.toString();
|
||||||
|
// parse SSE lines: event: <name> / data: <json>
|
||||||
|
process.stdout.write(s);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Best practices
|
||||||
|
- Always include `Accept: text/event-stream` for streaming.
|
||||||
|
- Expect multiple `reasoning_step` events, then exactly one `final` event.
|
||||||
|
- No token deltas are emitted; each message step contains the full assistant message text.
|
||||||
|
- Tool calls can be frequent; handle backpressure in your client.
|
||||||
|
- Keep your connection timeouts relaxed for long runs.
|
||||||
|
|
||||||
|
## Request examples (quick copy/paste)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Healthcheck
|
||||||
|
curl -s http://localhost:8080/api/v1/health
|
||||||
|
|
||||||
|
# List agents
|
||||||
|
curl -s -H "X-CAI-API-Key: $ALIAS_API_KEY" http://localhost:8080/api/v1/agents | jq .
|
||||||
|
|
||||||
|
# List models
|
||||||
|
curl -s -H "X-CAI-API-Key: $ALIAS_API_KEY" http://localhost:8080/api/v1/models | jq .
|
||||||
|
|
||||||
|
# List commands
|
||||||
|
curl -s -H "X-CAI-API-Key: $ALIAS_API_KEY" http://localhost:8080/api/v1/commands
|
||||||
|
|
||||||
|
# Run a command
|
||||||
|
curl -s -X POST http://localhost:8080/api/v1/commands/memory \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
-d '{"args": ["show"]}'
|
||||||
|
|
||||||
|
# Create a session
|
||||||
|
curl -s -X POST http://localhost:8080/api/v1/sessions \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
-d '{"agent": "redteam_agent", "model": "alias1", "stateful": true}'
|
||||||
|
|
||||||
|
# Interrupt and reload
|
||||||
|
curl -s -X POST -H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
http://localhost:8080/api/v1/sessions/<SESSION_ID>/interrupt
|
||||||
|
curl -s -X POST -H "Content-Type: application/json" -H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
-d '{"preserve_history": true}' \
|
||||||
|
http://localhost:8080/api/v1/sessions/<SESSION_ID>/reload
|
||||||
|
|
||||||
|
# Send a non-streamed prompt
|
||||||
|
curl -s -X POST http://localhost:8080/api/v1/sessions/<SESSION_ID>/messages \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
-d '{"input": "List current risks"}'
|
||||||
|
|
||||||
|
# Stream reasoning steps (SSE)
|
||||||
|
curl -N -X POST http://localhost:8080/api/v1/sessions/<SESSION_ID>/messages/stream \
|
||||||
|
-H 'Content-Type: application/json' \
|
||||||
|
-H 'Accept: text/event-stream' \
|
||||||
|
-H "X-CAI-API-Key: $ALIAS_API_KEY" \
|
||||||
|
-d '{"input": "List current risks"}'
|
||||||
|
|
||||||
|
# Reset and delete session
|
||||||
|
curl -s -X POST -H "X-CAI-API-Key: $ALIAS_API_KEY" http://localhost:8080/api/v1/sessions/<SESSION_ID>/reset
|
||||||
|
curl -s -X DELETE -H "X-CAI-API-Key: $ALIAS_API_KEY" http://localhost:8080/api/v1/sessions/<SESSION_ID>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example CLIs
|
||||||
|
|
||||||
|
- `examples/cai_api_cli.py` — minimal loop: prompts → responses.
|
||||||
|
- `examples/cai_api_tester.py` — interactive menu that covers all endpoints including streaming.
|
||||||
|
### GET /api/v1/agents
|
||||||
|
- Description: List available agents and patterns in the runtime (from `cai.agents`).
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
- Response 200 (AgentsResponse):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": [
|
||||||
|
{
|
||||||
|
"name": "redteam_agent",
|
||||||
|
"description": "...",
|
||||||
|
"type": "agent",
|
||||||
|
"pattern_type": null,
|
||||||
|
"tools": [
|
||||||
|
{"name": "nmap_scan", "description": "Scan a host or subnet"},
|
||||||
|
{"name": "http_get", "description": "Fetch a URL"}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "swarm_pattern",
|
||||||
|
"description": "Swarm agentic pattern",
|
||||||
|
"type": "pattern",
|
||||||
|
"pattern_type": "swarm",
|
||||||
|
"tools": []
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### GET /api/v1/models
|
||||||
|
- Description: List known models by combining predefined model catalog and `pricings/pricing.json` if present.
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
- Response 200 (ModelsResponse):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"models": [
|
||||||
|
{
|
||||||
|
"name": "alias1",
|
||||||
|
"provider": "OpenAI",
|
||||||
|
"category": "Alias",
|
||||||
|
"description": "Best model for Cybersecurity AI tasks",
|
||||||
|
"input_cost": 0.50,
|
||||||
|
"output_cost": 0.50,
|
||||||
|
"pricing": {
|
||||||
|
"input_cost_per_token": 0.000005,
|
||||||
|
"output_cost_per_token": 0.000005,
|
||||||
|
"max_tokens": 128000,
|
||||||
|
"max_input_tokens": 200000,
|
||||||
|
"max_output_tokens": 128000,
|
||||||
|
"supports_function_calling": true,
|
||||||
|
"supports_vision": true,
|
||||||
|
"supports_response_schema": true,
|
||||||
|
"supports_tool_choice": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### POST /api/v1/sessions/{id}/interrupt
|
||||||
|
- Description: Interrupt the currently running work (if any) for the given session. Cancels the active server-side run task.
|
||||||
|
- Headers: `X-CAI-API-Key`
|
||||||
|
- Response 200:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"interrupted": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /api/v1/sessions/{id}/reload
|
||||||
|
- Description: Recreate the session’s agent. Optionally preserve message history.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`
|
||||||
|
- Body:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"preserve_history": true}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Response 200: SessionDetailModel
|
||||||
|
|
||||||
|
<!-- Removed: /api/v1/sessions/{id}/ux/summarize and /api/v1/sessions/{id}/ux/title endpoints -->
|
||||||
|
|
||||||
|
### POST /api/v1/sessions/{id}/ux/final_message/stream_tokens (SSE)
|
||||||
|
- Description: Stream a final assistant message (token-level) that explains to the user what just happened. Your app calls this after a task completes, sending a prompt (tone/instructions) and optionally the steps you observed client-side; if you omit steps, the backend uses server-side steps.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`, `Accept: text/event-stream`
|
||||||
|
- Body (FinalMessageRequest):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"prompt": "Explain to the user what we found and next steps.",
|
||||||
|
"steps": [ /* optional: client-collected steps; otherwise server uses session.last_steps */ ],
|
||||||
|
"include_history": true,
|
||||||
|
"max_turns": 8
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Stream events:
|
||||||
|
- `event: token` with `{ "type": "message_start" }`
|
||||||
|
- `event: token` with `{ "type": "token_delta", "text": "..." }` repeated
|
||||||
|
- `event: token` with `{ "type": "message_end" }`
|
||||||
|
- `event: reasoning_step` may appear if the UX agent emits steps
|
||||||
|
- `event: final` with `{ "steps": [...], "final_message": "...", "final_output": ... }`
|
||||||
|
|
||||||
|
Notes for iOS
|
||||||
|
|
||||||
|
### POST /api/v1/ux/title
|
||||||
|
- Description: Genera un título conciso mediante una única tool call en el modelo `alias1` vía LiteLLM. No usa sesiones.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`
|
||||||
|
- Body:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"messages": [
|
||||||
|
{"role": "user", "content": "Analiza CVE-2024-..."}
|
||||||
|
],
|
||||||
|
"title_hint": "(opcional)"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Response 200:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"title": "Analizando CVE-2024-..."}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /api/v1/ux/summarize
|
||||||
|
- Description: Devuelve un resumen en una línea usando una única tool call en `alias1` vía LiteLLM. No usa sesiones.
|
||||||
|
- Headers: `X-CAI-API-Key`, `Content-Type: application/json`
|
||||||
|
- Body:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"messages": [
|
||||||
|
{"role": "user", "content": "Escanea 10.0.0.5"}
|
||||||
|
],
|
||||||
|
"steps": [
|
||||||
|
{"type": "tool_call", "agent": "Red Team", "tool": "nmap_scan", "arguments": {"target": "10.0.0.5"}},
|
||||||
|
{"type": "tool_output", "agent": "Red Team"}
|
||||||
|
],
|
||||||
|
"max_len": 100
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Response 200:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"summary_text": "Tool output procesado por Red Team"}
|
||||||
|
```
|
||||||
|
|
||||||
|
Implementation notes
|
||||||
|
- Ambos endpoints fuerzan `tool_choice: required` con una única función `produce_title_and_summary` y usan siempre `model: alias1` con `api_base` Alias y `ALIAS_API_KEY`.
|
||||||
|
- El servidor no almacena ni lee estado de sesión.
|
||||||
|
- Call this to stream the “final message” of a task. Use a UX prompt tuned to your voice (“Explain briefly in a friendly tone, with next steps”).
|
||||||
|
- If you already collected steps client-side, pass them; otherwise the backend uses `session.last_steps`.
|
||||||
|
- Render arriving `token_delta` chunks into the chat bubble; close on `message_end`/`final`.
|
||||||
|
|
@ -38,6 +38,7 @@ nav:
|
||||||
- Why CAI PRO?: cai_pro.md
|
- Why CAI PRO?: cai_pro.md
|
||||||
- Alias1 Model: cai_pro_alias1.md
|
- Alias1 Model: cai_pro_alias1.md
|
||||||
- Exclusive Features: cai_pro_features.md
|
- Exclusive Features: cai_pro_features.md
|
||||||
|
- '⭐ API Server (CAI PRO)': api.md
|
||||||
- Pricing & Plans: cai_pro_pricing.md
|
- Pricing & Plans: cai_pro_pricing.md
|
||||||
- Get Started with PRO: cai_pro_quickstart.md
|
- Get Started with PRO: cai_pro_quickstart.md
|
||||||
- Contact Sales: cai_pro_contact.md
|
- Contact Sales: cai_pro_contact.md
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue