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):

{
  "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):

{
  "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:

{
  "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.

{
  "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.

{
  "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:

{
  "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