From c55facf7ac3d9f21b09c7cbfd5bcc71d2b7505bf Mon Sep 17 00:00:00 2001 From: Adriano Dal Pastro Date: Mon, 25 May 2026 21:12:38 +0000 Subject: [PATCH] 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) --- docs/agent-guide.md | 264 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 docs/agent-guide.md diff --git a/docs/agent-guide.md b/docs/agent-guide.md new file mode 100644 index 0000000..f1485da --- /dev/null +++ b/docs/agent-guide.md @@ -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 +```