Adriano Dal Pastro
104 lines
2.7 KiB
Markdown
104 lines
2.7 KiB
Markdown
# 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:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edita .env: imposta API_KEY e le altre variabili
|
|
```
|
|
|
|
2. Avvia il sistema:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
3. Autentica Claude Code nel worker (nel container attivo, non con `run --rm`):
|
|
```bash
|
|
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:
|
|
```bash
|
|
curl -H "X-Api-Key: TUA_KEY" http://localhost:8000/api/health
|
|
```
|
|
|
|
## Sviluppo locale
|
|
|
|
```bash
|
|
uv sync --all-groups
|
|
cp .env.example .env
|
|
# Edita .env
|
|
uv run dev
|
|
```
|
|
|
|
## Test
|
|
|
|
```bash
|
|
uv run pytest -v
|
|
```
|
|
|
|
## API
|
|
|
|
Documentazione interattiva:
|
|
- Swagger UI: `https://opus-agent.tielogic.xyz/docs`
|
|
- ReDoc: `https://opus-agent.tielogic.xyz/redoc`
|
|
|
|
### Esempio d'uso
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|