OpusAgent

Servizio self-hosted per l'interazione programmatica con i modelli Anthropic tramite Claude Code SDK, sfruttando un abbonamento Claude Pro/Max esistente.

Architettura

Due container Docker:

• fastapi-service — API REST, autenticazione, coda richieste, rate limiting
• claude-worker — Processamento richieste via Claude Code SDK

Setup

Prerequisiti

• Docker e Docker Compose
• Un abbonamento Claude Pro/Max attivo

Prima installazione

1. Copia e configura l'environment:

   cp .env.example .env
   # Edita .env: imposta API_KEY e le altre variabili
   

2. Avvia il sistema:

   docker compose up -d
   

3. Autentica Claude Code nel worker (nel container attivo, non con run --rm):

   docker compose exec claude-worker npx claude login
   

   Le credenziali vengono salvate nel volume Docker claude-auth (mount: /root/.claude) e persistono tra riavvii e rebuild. Si perdono solo con docker compose down -v.

4. Verifica:

   curl -H "X-Api-Key: TUA_KEY" http://localhost:8000/api/health
   

Sviluppo locale

uv sync --all-groups
cp .env.example .env
# Edita .env
uv run dev

Test

uv run pytest -v

API

Documentazione interattiva:

• Swagger UI: https://opus-agent.tielogic.xyz/docs
• ReDoc: https://opus-agent.tielogic.xyz/redoc

Modelli disponibili

curl http://localhost:8000/api/models -H "X-Api-Key: TUA_KEY"

Ritorna i modelli disponibili dall'SDK (default, opus, sonnet, opusplan) e il modello di default configurato. Gli alias possono essere usati nel campo model di topic e richieste.

Esempio d'uso

# Crea un argomento
curl -X POST http://localhost:8000/api/topics \
  -H "X-Api-Key: TUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "coding", "system_prompt": "Sei un esperto sviluppatore."}'

# Invia una richiesta
curl -X POST http://localhost:8000/api/requests \
  -H "X-Api-Key: TUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Come implemento JWT in FastAPI?", "topic_id": "ID_TOPIC"}'

# Controlla il risultato
curl http://localhost:8000/api/requests/ID_RICHIESTA \
  -H "X-Api-Key: TUA_KEY"

Sessioni multi-turn

# Primo messaggio: session_id "new" o un ID personalizzato
curl -X POST http://localhost:8000/api/requests \
  -H "X-Api-Key: TUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Mi chiamo Marco.", "topic_id": "ID_TOPIC", "session_id": "new"}'

# Il risultato contiene il session_id (generato dall'SDK)
# Usalo per i messaggi successivi nella stessa conversazione
curl -X POST http://localhost:8000/api/requests \
  -H "X-Api-Key: TUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Come mi chiamo?", "topic_id": "ID_TOPIC", "session_id": "SESSION_ID_DAL_RISULTATO"}'

Il campo sdk_conversation_id nella risposta contiene l'ID interno della conversazione Claude Code SDK, usato automaticamente per il resume nei turni successivi.