Adriano/opus-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document sdk_conversation_id and multi-turn session flow

Browse Source 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Adriano Dal Pastro
2026-05-25 21:01:03 +00:00
parent 9b68f772f6
commit ad38cf7eaf
2 changed files with 29 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+9 -3
View File
@@ -45,7 +45,7 @@ Client → Traefik (HTTPS) → FastAPI (Python, :8000) ↔ Node.js Worker (:3001
Three tables in SQLite: Three tables in SQLite:
- **topics**: id (UUID), name (unique), system_prompt, summary, model (nullable), timestamps - **topics**: id (UUID), name (unique), system_prompt, summary, model (nullable), timestamps
- **requests**: id (UUID), session_id, topic_id (FK), prompt, result, error, model, summarize (bool), status (pending/processing/completed/failed), timestamps - **requests**: id (UUID), session_id, sdk_conversation_id, topic_id (FK), prompt, result, error, model, summarize (bool), status (pending/processing/completed/failed), timestamps
- **closed_sessions**: session_id (PK), closed_at - **closed_sessions**: session_id (PK), closed_at
## API Endpoints ## API Endpoints
@@ -62,12 +62,18 @@ All require `X-Api-Key` header. All responses use envelope: `{success, data, err
1. `POST /api/requests` → 202 Accepted (queued) 1. `POST /api/requests` → 202 Accepted (queued)
2. Background loop picks oldest pending, calls worker `POST /process` 2. Background loop picks oldest pending, calls worker `POST /process`
3. Worker runs Claude Code SDK (`query()`) with optional session resume 3. Worker runs Claude Code SDK (`query()` async iterable) with optional session resume
4. Result stored in DB; optional incremental summary appended to topic 4. Result stored in DB; SDK conversation ID saved in `sdk_conversation_id`; optional incremental summary appended to topic
5. Client polls `GET /api/requests/{id}` for result 5. Client polls `GET /api/requests/{id}` for result
Model resolution: request-level > topic-level > `CLAUDE_MODEL` env var. Model resolution: request-level > topic-level > `CLAUDE_MODEL` env var.
### Multi-turn sessions
- `session_id: "new"` → stored as NULL; after completion, set to SDK's conversation ID
- Custom `session_id` → preserved as-is; SDK conversation ID stored separately in `sdk_conversation_id`
- Resume logic: queue looks up `sdk_conversation_id` from previous completed requests in the same session; only passes it to worker if found (avoids resume on non-existent SDK sessions)
## Commands ## Commands
```bash ```bash
README.md
+20
View File
@@ -81,3 +81,23 @@ curl -X POST http://localhost:8000/api/requests \
curl http://localhost:8000/api/requests/ID_RICHIESTA \ curl http://localhost:8000/api/requests/ID_RICHIESTA \
-H "X-Api-Key: TUA_KEY" -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.