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
 ```