opus-agent/docs/agent-guide.md

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