docs: add API guide for AI agents

Complete reference for interacting with OpusAgent: auth, async flow, multi-turn sessions, model resolution, summarization, and error handling. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 21:12:38 +00:00
parent 5e763a2e37
commit c55facf7ac
1 changed files with 264 additions and 0 deletions
@@ -0,0 +1,264 @@
+# OpusAgent - Guida per Agenti AI
+
+Questo documento spiega come interagire con l'API REST di OpusAgent.
+OpusAgent e' un proxy che inoltra richieste ai modelli Claude tramite Claude Code SDK.
+
+## Informazioni base
+
+- **Base URL**: `https://opus-agent.tielogic.xyz`
+- **Autenticazione**: header `X-Api-Key` obbligatorio su ogni richiesta
+- **Formato risposte**: JSON con envelope `{"success": bool, "data": any, "error": {"code": str, "message": str} | null}`
+- **Elaborazione asincrona**: le richieste vengono accodate e processate sequenzialmente (FIFO)
+
+## Flusso operativo
+
+### 1. Crea un topic
+
+Un topic definisce il contesto della conversazione (system prompt) e opzionalmente un modello di default.
+
+```
+POST /api/topics
+Content-Type: application/json
+X-Api-Key: TUA_KEY
+
+{
+  "name": "analisi-dati",
+  "system_prompt": "Sei un esperto analista dati. Rispondi in italiano.",
+  "model": "sonnet"  // opzionale, default dal server
+}
+```
+
+Risposta (201):
+```json
+{
+  "success": true,
+  "data": {
+    "id": "uuid-del-topic",
+    "name": "analisi-dati",
+    "system_prompt": "...",
+    "summary": "",
+    "model": "sonnet",
+    "created_at": "...",
+    "updated_at": "..."
+  }
+}
+```
+
+### 2. Invia una richiesta
+
+Le richieste vengono accodate e processate in background. La risposta immediata e' un 202 Accepted con l'ID della richiesta.
+
+```
+POST /api/requests
+Content-Type: application/json
+X-Api-Key: TUA_KEY
+
+{
+  "topic_id": "uuid-del-topic",
+  "prompt": "Analizza i trend di vendita Q1 2026",
+  "model": "opus",       // opzionale, sovrascrive il modello del topic
+  "session_id": "new",   // opzionale, per conversazioni multi-turn
+  "summarize": true       // opzionale, genera riassunto incrementale nel topic
+}
+```
+
+Risposta (202):
+```json
+{
+  "success": true,
+  "data": {
+    "id": "uuid-della-richiesta",
+    "session_id": null,
+    "status": "pending",
+    "created_at": "..."
+  }
+}
+```
+
+### 3. Attendi il risultato (polling)
+
+Interroga periodicamente lo stato della richiesta fino a `status: "completed"` o `status: "failed"`.
+
+```
+GET /api/requests/{id}
+X-Api-Key: TUA_KEY
+```
+
+Risposta quando completata:
+```json
+{
+  "success": true,
+  "data": {
+    "id": "uuid-della-richiesta",
+    "session_id": "sdk-conversation-id",
+    "topic_id": "uuid-del-topic",
+    "prompt": "Analizza i trend di vendita Q1 2026",
+    "model": "opus",
+    "summarize": true,
+    "status": "completed",
+    "result": "Risposta di Claude...",
+    "error": null,
+    "created_at": "...",
+    "completed_at": "...",
+    "sdk_conversation_id": "sdk-uuid"
+  }
+}
+```
+
+**Intervallo di polling consigliato**: 2-3 secondi. Il tempo medio di risposta e' 3-5 secondi per richieste semplici.
+
+**Stati possibili**: `pending` -> `processing` -> `completed` | `failed`
+
+## Conversazioni multi-turn
+
+Per mantenere il contesto tra messaggi successivi, usa le sessioni.
+
+### Prima richiesta
+
+Invia con `"session_id": "new"` oppure un ID personalizzato a tua scelta.
+
+```json
+{
+  "topic_id": "uuid",
+  "prompt": "Mi chiamo Marco. Lavorero' su un progetto Python.",
+  "session_id": "new"
+}
+```
+
+Il `session_id` nella risposta 202 sara' `null`. Dopo il completamento, il campo `session_id` conterra' l'ID della conversazione generato dall'SDK.
+
+### Richieste successive
+
+Usa il `session_id` ottenuto dal risultato della prima richiesta completata.
+
+```json
+{
+  "topic_id": "uuid",
+  "prompt": "Come mi chiamo? Su cosa lavoriamo?",
+  "session_id": "session-id-dal-risultato-precedente"
+}
+```
+
+Claude ricordera' tutto il contesto della conversazione.
+
+### Session ID personalizzato
+
+Puoi passare un tuo ID (es. `"progetto-alpha-chat-1"`) invece di `"new"`. Il sistema lo mantiene come identificativo della sessione e gestisce internamente la mappatura con la conversazione SDK.
+
+### Chiudere una sessione
+
+```
+DELETE /api/sessions/{session_id}
+X-Api-Key: TUA_KEY
+```
+
+Dopo la chiusura, nuove richieste con lo stesso `session_id` verranno rifiutate con status 410 Gone.
+
+## Risoluzione del modello
+
+Il modello usato segue questa priorita' (dal piu' alto al piu' basso):
+
+1. **Campo `model` nella richiesta** - sovrascrive tutto
+2. **Campo `model` nel topic** - default per il topic
+3. **Variabile d'ambiente `CLAUDE_MODEL`** - default globale del server
+
+### Valori accettati per il campo model
+
+Alias corti (consigliati):
+- `default` - Opus o Sonnet in base ai limiti d'uso
+- `opus` - Opus 4.1, per task complessi
+- `sonnet` - Sonnet 4, per uso quotidiano
+- `opusplan` - Opus in plan mode, Sonnet altrimenti
+
+Model ID completi:
+- `claude-opus-4-7`
+- `claude-sonnet-4-6`
+- `claude-haiku-4-5-20251001`
+
+Per ottenere la lista aggiornata dei modelli disponibili:
+
+```
+GET /api/models
+X-Api-Key: TUA_KEY
+```
+
+## Riassunti automatici
+
+### Riassunto incrementale
+
+Aggiungi `"summarize": true` alla richiesta. Dopo il completamento, una sintesi di 1-2 frasi viene appesa al campo `summary` del topic con la data.
+
+### Riassunto completo
+
+Rigenera il riassunto del topic analizzando tutte le richieste completate:
+
+```
+POST /api/topics/{id}/summarize
+X-Api-Key: TUA_KEY
+```
+
+Il summary viene sovrascritto con un'overview completa di tutte le interazioni.
+
+## Riferimento completo degli endpoint
+
+| Metodo | Endpoint | Descrizione |
+|--------|----------|-------------|
+| GET | `/api/health` | Stato del sistema (DB, worker) |
+| GET | `/api/models` | Modelli Claude disponibili |
+| POST | `/api/topics` | Crea topic |
+| GET | `/api/topics` | Lista topic |
+| GET | `/api/topics/{id}` | Dettaglio topic |
+| PUT | `/api/topics/{id}` | Aggiorna topic |
+| DELETE | `/api/topics/{id}` | Elimina topic (fallisce se ha richieste pendenti) |
+| POST | `/api/topics/{id}/summarize` | Rigenera riassunto completo |
+| POST | `/api/requests` | Invia richiesta (202 Accepted) |
+| GET | `/api/requests` | Lista richieste (filtri: `?status=`, `?topic_id=`, `?session_id=`) |
+| GET | `/api/requests/{id}` | Stato e risultato richiesta |
+| DELETE | `/api/requests/{id}` | Elimina richiesta pendente |
+| GET | `/api/sessions` | Lista sessioni attive |
+| DELETE | `/api/sessions/{id}` | Chiudi sessione |
+
+## Gestione errori
+
+Le risposte di errore seguono lo stesso formato envelope:
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Topic not found"
+  }
+}
+```
+
+Codici HTTP comuni:
+- **202**: richiesta accettata e accodata
+- **400**: parametri mancanti o invalidi
+- **403**: API key mancante o errata
+- **404**: risorsa non trovata
+- **409**: conflitto (es. nome topic duplicato)
+- **410**: sessione chiusa
+- **429**: rate limit superato
+
+## Rate limiting
+
+Le richieste `POST /api/requests` sono limitate per API key:
+- **Per minuto**: configurabile (default 10)
+- **Per ora**: configurabile (default 100)
+
+Le altre operazioni (lettura, topic CRUD) non hanno limiti.
+
+## Esempio completo di workflow
+
+```
+1. GET  /api/models                     -> scegli il modello
+2. POST /api/topics                     -> crea il contesto
+3. POST /api/requests (session_id=new)  -> primo messaggio
+4. GET  /api/requests/{id}              -> polling fino a completed
+5. POST /api/requests (session_id=...)  -> messaggi successivi
+6. GET  /api/requests/{id}              -> polling risultato
+7. POST /api/topics/{id}/summarize      -> riassunto finale
+8. DELETE /api/sessions/{id}            -> chiudi sessione
+```