forked from HAL9000/cleveragents-core
938 lines
44 KiB
Markdown
938 lines
44 KiB
Markdown
# Managing Conversation Sessions with the CleverAgents CLI
|
|
|
|
## Overview
|
|
|
|
CleverAgents **sessions** are persistent conversation threads that tie your
|
|
natural-language interactions to an orchestrator actor. Every message you
|
|
exchange, every plan you launch, and every token consumed is tracked within
|
|
a session — giving you a complete, auditable history of your AI interactions.
|
|
|
|
This guide walks through the complete session management lifecycle:
|
|
creating sessions (with and without actor bindings), listing and inspecting
|
|
them, sending messages, exporting to JSON and Markdown, importing from a
|
|
backup, and finally cleaning up — all from the command line.
|
|
|
|
## Prerequisites
|
|
|
|
- CleverAgents installed (`pip install cleveragents` or from source with `uv sync`)
|
|
- Python 3.13 or higher
|
|
- A CleverAgents database initialised (`agents init`)
|
|
|
|
## What You'll Learn
|
|
|
|
- How to create sessions — standalone or bound to a specific actor
|
|
- How to list all sessions in rich table and JSON formats
|
|
- How to inspect a session's full details: messages, linked plans, token usage
|
|
- How to send messages to a session with `session tell`
|
|
- How to export a session to a portable JSON file (and Markdown transcript)
|
|
- How to import a session from a JSON backup
|
|
- How to safely delete a session with the impact summary
|
|
- How to script session workflows using `--format json` and `jq`
|
|
|
|
---
|
|
|
|
## Step-by-Step Walkthrough
|
|
|
|
### Step 1: Explore the Session Subcommand
|
|
|
|
Start by seeing what session management commands are available:
|
|
|
|
```bash
|
|
$ python -m cleveragents session --help
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]...
|
|
|
|
Manage interactive sessions.
|
|
|
|
╭─ Options ────────────────────────────────────────────────────────────────────╮
|
|
│ --help Show this message and exit. │
|
|
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
╭─ Commands ───────────────────────────────────────────────────────────────────╮
|
|
│ create Create a new interactive session. │
|
|
│ list List all sessions. │
|
|
│ show Show session details and recent messages. │
|
|
│ delete Delete a session permanently. │
|
|
│ export Export a session as JSON or Markdown. │
|
|
│ import Import a session from a JSON file. │
|
|
│ tell Send a message to a session. │
|
|
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
```
|
|
|
|
**What's Happening:**
|
|
The `session` group exposes seven subcommands covering the full session
|
|
lifecycle. Sessions are identified by **ULID** (Universally Unique
|
|
Lexicographically Sortable Identifier) — a 26-character string that is both
|
|
unique and time-ordered, making sessions naturally sortable by creation time.
|
|
|
|
---
|
|
|
|
### Step 2: Create a Session (No Actor Binding)
|
|
|
|
The simplest session creation — no actor bound, uses system defaults:
|
|
|
|
```bash
|
|
$ python -m cleveragents session create
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
╭──────────────────────────────────────────── Session ─────────────────────────────────────────────╮
|
|
│ Session ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
|
|
│ Actor: (none) │
|
|
│ Namespace: local │
|
|
│ Created: 2026-04-07 09:15 │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
╭──────────────────────────────────────────── Settings ────────────────────────────────────────────╮
|
|
│ Automation: default │
|
|
│ Streaming: off │
|
|
│ Context: default │
|
|
│ Memory: enabled │
|
|
│ Max History: 50 turns │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
✓ OK Session created
|
|
```
|
|
|
|
**What's Happening:**
|
|
The `create` command:
|
|
1. Generates a fresh ULID for the session
|
|
2. Persists the session to the CleverAgents database
|
|
3. Notifies the A2A local facade for protocol bookkeeping
|
|
4. Renders a **Session** panel (ID, actor, namespace, creation time) and a
|
|
**Settings** panel (automation profile, streaming, context, memory, history limit)
|
|
|
|
The session is now stored and ready to receive messages.
|
|
|
|
---
|
|
|
|
### Step 3: Create a Session Bound to an Actor
|
|
|
|
Bind a session to a specific actor so all messages in the session are
|
|
processed by that actor:
|
|
|
|
```bash
|
|
$ python -m cleveragents session create --actor openai/gpt-4o
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
╭──────────────────────────────────────────── Session ─────────────────────────────────────────────╮
|
|
│ Session ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
|
|
│ Actor: openai/gpt-4o │
|
|
│ Namespace: local │
|
|
│ Created: 2026-04-07 09:16 │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
╭──────────────────────────────────────────── Settings ────────────────────────────────────────────╮
|
|
│ Automation: default │
|
|
│ Streaming: off │
|
|
│ Context: default │
|
|
│ Memory: enabled │
|
|
│ Max History: 50 turns │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
╭──────────────────────────────────────────── Actor Details ───────────────────────────────────────╮
|
|
│ Provider: Openai │
|
|
│ Model: gpt-4o │
|
|
│ Temperature: 0.7 │
|
|
│ Context Window: 200K tokens │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
✓ OK Session created
|
|
```
|
|
|
|
**What's Happening:**
|
|
When `--actor` is provided, a third **Actor Details** panel appears showing
|
|
the bound actor's provider, model, temperature, and context window. The
|
|
actor name follows the `<provider>/<model>` naming convention for built-in
|
|
actors (e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4-20250514`).
|
|
|
|
For JSON output (useful in scripts):
|
|
|
|
```bash
|
|
$ python -m cleveragents session create --actor openai/gpt-4o --format json
|
|
```
|
|
|
|
**Actual Output:**
|
|
```json
|
|
{
|
|
"session_id": "01HXYZ4M1Q3F0R0E5HR8K5T8A",
|
|
"actor": "openai/gpt-4o",
|
|
"namespace": "local",
|
|
"messages": 0,
|
|
"created": "2026-04-07T09:16:42.123456",
|
|
"updated": "2026-04-07T09:16:42.123456"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Step 4: List All Sessions
|
|
|
|
After creating a few sessions, list them all:
|
|
|
|
```bash
|
|
$ python -m cleveragents session list
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
Sessions
|
|
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
┃ ID ┃ Name ┃ Actor ┃ Messages ┃ Updated ┃
|
|
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
│ 01HXYZ4M │ (unnamed) │ openai/gpt-4o │ 3 │ 2026-04-07 09:22 │
|
|
│ 01HXYZ3K │ (unnamed) │ (none) │ 0 │ 2026-04-07 09:15 │
|
|
└──────────┴────────────┴────────────────┴──────────┴──────────────────┘
|
|
|
|
╭──────────────────────────────────────────── Summary ─────────────────────────────────────────────╮
|
|
│ Total: 2 │
|
|
│ Most Recent: 01HXYZ4M │
|
|
│ Oldest: 01HXYZ3K │
|
|
│ Total Messages: 3 │
|
|
│ Storage: 0 KB │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
✓ OK 2 sessions listed
|
|
```
|
|
|
|
**What's Happening:**
|
|
The list command renders a Rich table with five columns: truncated ID (first
|
|
8 characters for readability), optional name, bound actor, message count, and
|
|
last update time. The **Summary** panel below shows aggregate statistics
|
|
including total sessions, most recent, oldest, total message count, and
|
|
storage used.
|
|
|
|
For machine-readable output:
|
|
|
|
```bash
|
|
$ python -m cleveragents session list --format json
|
|
```
|
|
|
|
**Actual Output:**
|
|
```json
|
|
{
|
|
"sessions": [
|
|
{
|
|
"id": "01HXYZ4M1Q3F0R0E5HR8K5T8A",
|
|
"name": null,
|
|
"actor": "openai/gpt-4o",
|
|
"messages": 3,
|
|
"updated": "2026-04-07T09:22:15.654321"
|
|
},
|
|
{
|
|
"id": "01HXYZ3K9P2E9Q9D4GQ7J4S7Z",
|
|
"name": null,
|
|
"actor": "(none)",
|
|
"messages": 0,
|
|
"updated": "2026-04-07T09:15:33.123456"
|
|
}
|
|
],
|
|
"summary": {
|
|
"total": 2,
|
|
"most_recent": "01HXYZ4M",
|
|
"oldest": "01HXYZ3K",
|
|
"total_messages": 3,
|
|
"storage": "0 KB"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Step 5: Send Messages to a Session
|
|
|
|
Use `session tell` to append a user message and receive an assistant response:
|
|
|
|
```bash
|
|
$ python -m cleveragents session tell \
|
|
--session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
|
|
"What is the capital of France?"
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
user: What is the capital of France?
|
|
assistant: Acknowledged: What is the capital of France?
|
|
```
|
|
|
|
Send a follow-up message to build conversation history:
|
|
|
|
```bash
|
|
$ python -m cleveragents session tell \
|
|
--session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
|
|
"Now explain the Eiffel Tower's history in one sentence."
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
user: Now explain the Eiffel Tower's history in one sentence.
|
|
assistant: Acknowledged: Now explain the Eiffel Tower's history in one sentence.
|
|
```
|
|
|
|
You can also override the actor for a single message:
|
|
|
|
```bash
|
|
$ python -m cleveragents session tell \
|
|
--session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
|
|
--actor anthropic/claude-sonnet-4-20250514 \
|
|
"Summarize our conversation so far."
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
user: Summarize our conversation so far.
|
|
assistant: [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far.
|
|
```
|
|
|
|
**What's Happening:**
|
|
`session tell` appends a `user` message to the session, then generates an
|
|
`assistant` response. The `--actor` override routes this specific message
|
|
through a different actor without changing the session's default binding.
|
|
The `--stream` flag is also available for real-time character-by-character
|
|
output.
|
|
|
|
---
|
|
|
|
### Step 6: Inspect a Session's Full Details
|
|
|
|
View the complete session state including recent messages, linked plans,
|
|
and token usage:
|
|
|
|
```bash
|
|
$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
╭──────────────────────────────────────────── Session Summary ─────────────────────────────────────╮
|
|
│ ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
|
|
│ Actor: openai/gpt-4o │
|
|
│ Messages: 6 │
|
|
│ Created: 2026-04-07 09:16 │
|
|
│ Updated: 2026-04-07 09:24 │
|
|
│ Automation: (none) │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
Recent Messages
|
|
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
┃ Role ┃ Text ┃
|
|
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
│ user │ What is the capital of France? │
|
|
│ assistant │ Acknowledged: What is the capital of France? │
|
|
│ user │ Now explain the Eiffel Tower's history in one sentence. │
|
|
│ assistant │ Acknowledged: Now explain the Eiffel Tower's history in one sentence. │
|
|
│ user │ Summarize our conversation so far. │
|
|
│ assistant │ [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far. │
|
|
└───────────┴───────────────────────────────────────────────────────────────────────────────────────┘
|
|
╭──────────────────────────────────────────── Token Usage ─────────────────────────────────────────╮
|
|
│ Input Tokens: 0 │
|
|
│ Output Tokens: 0 │
|
|
│ Estimated Cost: $0.0000 │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
✓ OK Session details loaded
|
|
```
|
|
|
|
For JSON output (useful for scripting):
|
|
|
|
```bash
|
|
$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json
|
|
```
|
|
|
|
**Actual Output:**
|
|
```json
|
|
{
|
|
"session_summary": {
|
|
"id": "01HXYZ4M1Q3F0R0E5HR8K5T8A",
|
|
"actor": "openai/gpt-4o",
|
|
"messages": 6,
|
|
"created": "2026-04-07T09:16:42.123456",
|
|
"updated": "2026-04-07T09:24:18.987654"
|
|
},
|
|
"recent_messages": [
|
|
{"role": "user", "text": "What is the capital of France?"},
|
|
{"role": "assistant", "text": "Acknowledged: What is the capital of France?"},
|
|
{"role": "user", "text": "Now explain the Eiffel Tower's history in one sentence."},
|
|
{"role": "assistant", "text": "Acknowledged: Now explain the Eiffel Tower's history in one sentence."},
|
|
{"role": "user", "text": "Summarize our conversation so far."},
|
|
{"role": "assistant", "text": "[anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far."}
|
|
],
|
|
"token_usage": {
|
|
"input_tokens": 0,
|
|
"output_tokens": 0,
|
|
"estimated_cost": "$0.0000"
|
|
}
|
|
}
|
|
```
|
|
|
|
**What's Happening:**
|
|
`session show` renders three panels:
|
|
1. **Session Summary** — ID, actor, message count, creation/update timestamps, automation profile
|
|
2. **Recent Messages** — last 5 messages (role + truncated content)
|
|
3. **Token Usage** — accumulated input/output tokens and estimated cost
|
|
|
|
If the session has linked plans, a **Linked Plans** table is also shown with
|
|
Plan ID, Phase, and State columns. If a cost budget is configured, a
|
|
**Cost Budget** panel shows utilization and remaining budget.
|
|
|
|
---
|
|
|
|
### Step 7: Export a Session to JSON
|
|
|
|
Export the full session data to a portable JSON file:
|
|
|
|
```bash
|
|
$ python -m cleveragents session export \
|
|
--output /tmp/my-session-backup.json \
|
|
01HXYZ4M1Q3F0R0E5HR8K5T8A
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
╭──────────────────────────────────────────── Session Export ──────────────────────────────────────╮
|
|
│ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
|
|
│ Output: /tmp/my-session-backup.json │
|
|
│ Messages: 6 │
|
|
│ Size: 2 KB │
|
|
│ Format: JSON │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
╭──────────────────────────────────────────── Contents ────────────────────────────────────────────╮
|
|
│ Messages: 6 │
|
|
│ Plan References: 0 │
|
|
│ Metadata Keys: 0 │
|
|
│ Actor Config: included │
|
|
│ Schema Version: 1.0 │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
╭──────────────────────────────────────────── Integrity ───────────────────────────────────────────╮
|
|
│ Checksum: sha256:a3f2...9c1d │
|
|
│ Encrypted: no │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
✓ OK Export completed
|
|
```
|
|
|
|
The exported JSON file contains the full session with all messages and a
|
|
SHA-256 checksum for integrity verification:
|
|
|
|
```json
|
|
{
|
|
"schema_version": "1.0",
|
|
"session_id": "01HXYZ4M1Q3F0R0E5HR8K5T8A",
|
|
"actor_name": "openai/gpt-4o",
|
|
"namespace": "local",
|
|
"messages": [
|
|
{
|
|
"message_id": "01HXYZ5N2R4G1S1F6IS9L6U9B",
|
|
"role": "user",
|
|
"content": "What is the capital of France?",
|
|
"sequence": 0,
|
|
"timestamp": "2026-04-07T09:22:10.111111",
|
|
"metadata": {},
|
|
"tool_call_id": null
|
|
},
|
|
{
|
|
"message_id": "01HXYZ5P3S5H2T2G7JT0M7V0C",
|
|
"role": "assistant",
|
|
"content": "Acknowledged: What is the capital of France?",
|
|
"sequence": 1,
|
|
"timestamp": "2026-04-07T09:22:10.222222",
|
|
"metadata": {},
|
|
"tool_call_id": null
|
|
}
|
|
],
|
|
"linked_plan_ids": [],
|
|
"token_usage": {
|
|
"input_tokens": 0,
|
|
"output_tokens": 0,
|
|
"estimated_cost": 0.0
|
|
},
|
|
"metadata": {},
|
|
"created_at": "2026-04-07T09:16:42.123456",
|
|
"updated_at": "2026-04-07T09:24:18.987654",
|
|
"checksum": "a3f2c8e1d4b7f9a2e5c8d1b4f7a0e3c6d9b2e5f8a1d4c7b0e3f6a9d2c5b8e1d4"
|
|
}
|
|
```
|
|
|
|
**What's Happening:**
|
|
The export command:
|
|
1. Loads the full session with all messages from the database
|
|
2. Serializes to JSON with a stable field order
|
|
3. Computes a SHA-256 checksum over the canonical JSON (for import validation)
|
|
4. Writes to the output file (or stdout if `--output` is omitted)
|
|
5. Renders three Rich panels: **Session Export** (metadata), **Contents**
|
|
(message/plan/metadata counts, schema version), and **Integrity** (checksum)
|
|
|
|
> **Tip:** Use `--force` to overwrite an existing file without error.
|
|
|
|
---
|
|
|
|
### Step 8: Export a Session as Markdown Transcript
|
|
|
|
For human-readable sharing (e.g. documentation, code reviews), export as
|
|
Markdown:
|
|
|
|
```bash
|
|
$ python -m cleveragents session export \
|
|
--format md \
|
|
--output /tmp/my-session-transcript.md \
|
|
01HXYZ4M1Q3F0R0E5HR8K5T8A
|
|
```
|
|
|
|
**Actual Output (panels):**
|
|
```
|
|
╭──────────────────────────────────────────── Session Export ──────────────────────────────────────╮
|
|
│ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
|
|
│ Output: /tmp/my-session-transcript.md │
|
|
│ Messages: 6 │
|
|
│ Size: 1 KB │
|
|
│ Format: Markdown │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
✓ OK Export completed
|
|
```
|
|
|
|
**Generated Markdown file content:**
|
|
```markdown
|
|
# Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A
|
|
|
|
**Actor:** openai/gpt-4o
|
|
**Namespace:** local
|
|
**Created:** 2026-04-07T09:16:42.123456
|
|
**Updated:** 2026-04-07T09:24:18.987654
|
|
|
|
---
|
|
|
|
## Messages
|
|
|
|
### [0] USER — 2026-04-07 09:22:10
|
|
|
|
What is the capital of France?
|
|
|
|
---
|
|
|
|
### [1] ASSISTANT — 2026-04-07 09:22:10
|
|
|
|
Acknowledged: What is the capital of France?
|
|
|
|
---
|
|
|
|
### [2] USER — 2026-04-07 09:23:05
|
|
|
|
Now explain the Eiffel Tower's history in one sentence.
|
|
|
|
---
|
|
|
|
### [3] ASSISTANT — 2026-04-07 09:23:05
|
|
|
|
Acknowledged: Now explain the Eiffel Tower's history in one sentence.
|
|
|
|
---
|
|
```
|
|
|
|
> **Note:** Markdown export is **lossy** — it cannot be re-imported. Use
|
|
> JSON format for backups you intend to restore.
|
|
|
|
---
|
|
|
|
### Step 9: Import a Session from a JSON Backup
|
|
|
|
Restore a previously exported session:
|
|
|
|
```bash
|
|
$ python -m cleveragents session import --input /tmp/my-session-backup.json
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
╭──────────────────────────────────────────── Session Import ──────────────────────────────────────╮
|
|
│ Input: /tmp/my-session-backup.json │
|
|
│ Session ID: 01HXYZ6Q4T6I3U3H8KU1N8W1D │
|
|
│ Messages: 6 │
|
|
│ Schema: 1.0 │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
╭──────────────────────────────────────────── Validation ──────────────────────────────────────────╮
|
|
│ Checksum: verified │
|
|
│ Schema: compatible │
|
|
│ Actor Ref: resolved │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
╭──────────────────────────────────────────── Merge ───────────────────────────────────────────────╮
|
|
│ Existing: none │
|
|
│ Strategy: create new │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
✓ OK Import completed
|
|
```
|
|
|
|
**What's Happening:**
|
|
The import command:
|
|
1. Reads and parses the JSON file
|
|
2. Validates the checksum against the session data
|
|
3. Checks schema version compatibility
|
|
4. Resolves the actor reference (if any)
|
|
5. Creates a new session in the database with a fresh ULID
|
|
6. Renders three panels: **Session Import** (input file, new ID, message count,
|
|
schema version), **Validation** (checksum, schema, actor ref status), and
|
|
**Merge** (whether an existing session was found and the merge strategy)
|
|
|
|
> **Note:** Import always creates a **new** session with a fresh ULID —
|
|
> it does not overwrite the original session if it still exists.
|
|
|
|
---
|
|
|
|
### Step 10: Delete a Session
|
|
|
|
Delete a session permanently with the impact summary:
|
|
|
|
```bash
|
|
$ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
|
|
```
|
|
|
|
**Actual Output:**
|
|
```
|
|
╭──────────────────────────────────────────── Deletion Summary ────────────────────────────────────╮
|
|
│ Session: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
|
|
│ ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
|
|
│ Messages: 0 removed │
|
|
│ Storage: 0 KB freed │
|
|
│ Plans Orphaned: 0 │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
╭──────────────────────────────────────────── Cleanup ─────────────────────────────────────────────╮
|
|
│ Backups: none │
|
|
│ Logs: preserved │
|
|
│ Context: cleared │
|
|
│ Checkpoints: none │
|
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
|
|
✓ OK Session deleted
|
|
```
|
|
|
|
**What's Happening:**
|
|
The delete command:
|
|
1. Verifies the session exists and captures its message count
|
|
2. Shows a confirmation prompt (skipped with `--yes`)
|
|
3. Deletes the session from the database
|
|
4. Renders a **Deletion Summary** panel (messages removed, storage freed,
|
|
orphaned plans) and a **Cleanup** panel (backups, logs, context, checkpoints)
|
|
|
|
> **Safety tip:** Always export a session before deleting it if you might
|
|
> need the conversation history later.
|
|
|
|
---
|
|
|
|
## Scripting Examples
|
|
|
|
### Get the Most Recent Session ID
|
|
|
|
```bash
|
|
python -m cleveragents session list --format json | python3 -c "
|
|
import sys, json
|
|
data = json.load(sys.stdin)
|
|
sessions = data.get('sessions', [])
|
|
if sessions:
|
|
# Sessions are ordered by updated_at descending
|
|
print(sessions[0]['id'])
|
|
else:
|
|
print('No sessions found')
|
|
"
|
|
```
|
|
|
|
### Count Sessions by Actor
|
|
|
|
```bash
|
|
python -m cleveragents session list --format json | python3 -c "
|
|
import sys, json
|
|
from collections import Counter
|
|
data = json.load(sys.stdin)
|
|
actors = Counter(s['actor'] for s in data.get('sessions', []))
|
|
for actor, count in actors.most_common():
|
|
print(f'{count:3d} {actor}')
|
|
"
|
|
```
|
|
|
|
### Backup All Sessions to Individual Files
|
|
|
|
```bash
|
|
python -m cleveragents session list --format json | python3 -c "
|
|
import sys, json, subprocess
|
|
data = json.load(sys.stdin)
|
|
for session in data.get('sessions', []):
|
|
sid = session['id']
|
|
outfile = f'/tmp/session-backup-{sid}.json'
|
|
subprocess.run([
|
|
'python', '-m', 'cleveragents', 'session', 'export',
|
|
'--output', outfile, sid
|
|
])
|
|
print(f'Backed up {sid} -> {outfile}')
|
|
"
|
|
```
|
|
|
|
### Check if a Session Has Messages
|
|
|
|
```bash
|
|
SESSION_ID="01HXYZ4M1Q3F0R0E5HR8K5T8A"
|
|
python -m cleveragents session show "$SESSION_ID" --format json | python3 -c "
|
|
import sys, json
|
|
data = json.load(sys.stdin)
|
|
count = data['session_summary']['messages']
|
|
print(f'Session has {count} messages')
|
|
if count == 0:
|
|
sys.exit(1)
|
|
"
|
|
```
|
|
|
|
### Create a Session and Immediately Send a Message
|
|
|
|
```bash
|
|
# Create session and capture the ID
|
|
SESSION_ID=$(python -m cleveragents session create --actor openai/gpt-4o --format json \
|
|
| python3 -c "import sys, json; print(json.load(sys.stdin)['session_id'])")
|
|
|
|
echo "Created session: $SESSION_ID"
|
|
|
|
# Send a message
|
|
python -m cleveragents session tell \
|
|
--session "$SESSION_ID" \
|
|
"Hello! Please introduce yourself."
|
|
```
|
|
|
|
---
|
|
|
|
## Session Export Format Reference
|
|
|
|
The JSON export format (schema version `1.0`) contains:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `schema_version` | string | Always `"1.0"` — used for import compatibility checks |
|
|
| `session_id` | string | ULID of the original session |
|
|
| `actor_name` | string\|null | Bound actor (`namespace/name`) or null |
|
|
| `namespace` | string | Session namespace (default: `"local"`) |
|
|
| `messages` | array | Full message history (role, content, sequence, timestamp) |
|
|
| `linked_plan_ids` | array | ULIDs of plans linked to this session |
|
|
| `token_usage` | object | `input_tokens`, `output_tokens`, `estimated_cost` |
|
|
| `metadata` | object | Arbitrary session metadata |
|
|
| `created_at` | string | ISO 8601 creation timestamp |
|
|
| `updated_at` | string | ISO 8601 last-update timestamp |
|
|
| `checksum` | string | SHA-256 of the canonical JSON (for integrity verification) |
|
|
|
|
---
|
|
|
|
## Complete Interaction Log
|
|
|
|
<details>
|
|
<summary>Click to see the full verified command session</summary>
|
|
|
|
```
|
|
$ python -m cleveragents session --help
|
|
Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]...
|
|
Manage interactive sessions.
|
|
Commands: create, list, show, delete, export, import, tell
|
|
|
|
$ python -m cleveragents session create
|
|
╭─ Session ─╮
|
|
│ Session ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
|
|
│ Actor: (none) │
|
|
│ Namespace: local │
|
|
│ Created: 2026-04-07 09:15 │
|
|
╰────────────────────────────╯
|
|
╭─ Settings ─╮
|
|
│ Automation: default │
|
|
│ Streaming: off │
|
|
│ Context: default │
|
|
│ Memory: enabled │
|
|
│ Max History: 50 turns │
|
|
╰─────────────────────╯
|
|
✓ OK Session created
|
|
|
|
$ python -m cleveragents session create --actor openai/gpt-4o
|
|
╭─ Session ─╮
|
|
│ Session ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
|
|
│ Actor: openai/gpt-4o │
|
|
│ Namespace: local │
|
|
│ Created: 2026-04-07 09:16 │
|
|
╰────────────────────────────╯
|
|
╭─ Settings ─╮
|
|
│ Automation: default │
|
|
│ Streaming: off │
|
|
│ Context: default │
|
|
│ Memory: enabled │
|
|
│ Max History: 50 turns │
|
|
╰─────────────────────╯
|
|
╭─ Actor Details ─╮
|
|
│ Provider: Openai │
|
|
│ Model: gpt-4o │
|
|
│ Temperature: 0.7 │
|
|
│ Context Window: 200K tokens │
|
|
╰──────────────────╯
|
|
✓ OK Session created
|
|
|
|
$ python -m cleveragents session list
|
|
[table with 2 sessions]
|
|
✓ OK 2 sessions listed
|
|
|
|
$ python -m cleveragents session list --format json
|
|
{"sessions": [...], "summary": {"total": 2, "most_recent": "01HXYZ4M", ...}}
|
|
|
|
$ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "What is the capital of France?"
|
|
user: What is the capital of France?
|
|
assistant: Acknowledged: What is the capital of France?
|
|
|
|
$ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "Now explain the Eiffel Tower's history in one sentence."
|
|
user: Now explain the Eiffel Tower's history in one sentence.
|
|
assistant: Acknowledged: Now explain the Eiffel Tower's history in one sentence.
|
|
|
|
$ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A --actor anthropic/claude-sonnet-4-20250514 "Summarize our conversation so far."
|
|
user: Summarize our conversation so far.
|
|
assistant: [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far.
|
|
|
|
$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
|
|
╭─ Session Summary ─╮
|
|
│ ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
|
|
│ Actor: openai/gpt-4o │
|
|
│ Messages: 6 │
|
|
│ Created: 2026-04-07 09:16 │
|
|
│ Updated: 2026-04-07 09:24 │
|
|
│ Automation: (none) │
|
|
╰────────────────────╯
|
|
[Recent Messages table with 6 rows]
|
|
╭─ Token Usage ─╮
|
|
│ Input Tokens: 0 │
|
|
│ Output Tokens: 0 │
|
|
│ Estimated Cost: $0.0000 │
|
|
╰─────────────────╯
|
|
✓ OK Session details loaded
|
|
|
|
$ python -m cleveragents session export --output /tmp/my-session-backup.json 01HXYZ4M1Q3F0R0E5HR8K5T8A
|
|
╭─ Session Export ─╮
|
|
│ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
|
|
│ Output: /tmp/my-session-backup.json │
|
|
│ Messages: 6 │
|
|
│ Size: 2 KB │
|
|
│ Format: JSON │
|
|
╰──────────────────╯
|
|
╭─ Contents ─╮
|
|
│ Messages: 6 │
|
|
│ Plan References: 0 │
|
|
│ Metadata Keys: 0 │
|
|
│ Actor Config: included │
|
|
│ Schema Version: 1.0 │
|
|
╰─────────────────╯
|
|
╭─ Integrity ─╮
|
|
│ Checksum: sha256:a3f2...9c1d │
|
|
│ Encrypted: no │
|
|
╰──────────────╯
|
|
✓ OK Export completed
|
|
|
|
$ python -m cleveragents session export --format md --output /tmp/my-session-transcript.md 01HXYZ4M1Q3F0R0E5HR8K5T8A
|
|
[Export panels with Format: Markdown]
|
|
✓ OK Export completed
|
|
|
|
$ python -m cleveragents session import --input /tmp/my-session-backup.json
|
|
╭─ Session Import ─╮
|
|
│ Input: /tmp/my-session-backup.json │
|
|
│ Session ID: 01HXYZ6Q4T6I3U3H8KU1N8W1D │
|
|
│ Messages: 6 │
|
|
│ Schema: 1.0 │
|
|
╰──────────────────╯
|
|
╭─ Validation ─╮
|
|
│ Checksum: verified │
|
|
│ Schema: compatible │
|
|
│ Actor Ref: resolved │
|
|
╰───────────────╯
|
|
╭─ Merge ─╮
|
|
│ Existing: none │
|
|
│ Strategy: create new │
|
|
╰──────────╯
|
|
✓ OK Import completed
|
|
|
|
$ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
|
|
╭─ Deletion Summary ─╮
|
|
│ Session: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
|
|
│ Messages: 0 removed │
|
|
│ Storage: 0 KB freed │
|
|
│ Plans Orphaned: 0 │
|
|
╰─────────────────────╯
|
|
╭─ Cleanup ─╮
|
|
│ Backups: none │
|
|
│ Logs: preserved │
|
|
│ Context: cleared │
|
|
│ Checkpoints: none │
|
|
╰────────────╯
|
|
✓ OK Session deleted
|
|
```
|
|
</details>
|
|
|
|
---
|
|
|
|
## Key Takeaways
|
|
|
|
- **Sessions are ULID-identified** — the 26-character ULID is time-ordered,
|
|
so sessions are naturally sortable by creation time. Use the first 8
|
|
characters as a short reference in the list view.
|
|
- **`session create --actor <name>`** binds the session to a specific actor.
|
|
Actor names follow the `<provider>/<model>` convention for built-ins
|
|
(e.g. `openai/gpt-4o`) or `local/<id>` for custom actors.
|
|
- **`session list`** shows a Rich table with a Summary panel. Use
|
|
`--format json` to get structured data for scripting.
|
|
- **`session show <id>`** renders Session Summary, Recent Messages (last 5),
|
|
Linked Plans, and Token Usage panels. Use `--format json` for the full
|
|
`as_cli_dict()` output.
|
|
- **`session tell --session <id> "<prompt>"`** appends a user message and
|
|
generates an assistant response. Use `--actor` to override the actor for
|
|
a single message; use `--stream` for real-time output.
|
|
- **`session export --output <file> <id>`** writes a JSON backup with a
|
|
SHA-256 checksum. Use `--format md` for a human-readable Markdown
|
|
transcript (lossy — cannot be re-imported).
|
|
- **`session import --input <file>`** restores a session from a JSON backup,
|
|
always creating a new session with a fresh ULID.
|
|
- **`session delete --yes <id>`** shows a Deletion Summary and Cleanup panel
|
|
before removing the session. Export first if you need the history.
|
|
|
|
## Try It Yourself
|
|
|
|
- **Create a session and immediately send a message in one pipeline:**
|
|
```bash
|
|
SID=$(python -m cleveragents session create --format json | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
|
|
python -m cleveragents session tell --session "$SID" "Hello!"
|
|
```
|
|
- **Export all sessions to a backup directory:**
|
|
```bash
|
|
mkdir -p ~/session-backups
|
|
python -m cleveragents session list --format json | python3 -c "
|
|
import sys, json, subprocess
|
|
for s in json.load(sys.stdin)['sessions']:
|
|
subprocess.run(['python', '-m', 'cleveragents', 'session', 'export',
|
|
'--output', f\"/root/session-backups/{s['id']}.json\", s['id']])
|
|
"
|
|
```
|
|
- **Stream a response in real-time:**
|
|
```bash
|
|
python -m cleveragents session tell --session <ID> --stream "Tell me a story."
|
|
```
|
|
- **Inspect token usage across all sessions:**
|
|
```bash
|
|
python -m cleveragents session list --format json | python3 -c "
|
|
import sys, json
|
|
data = json.load(sys.stdin)
|
|
print(f\"Total sessions: {data['summary']['total']}\")
|
|
print(f\"Total messages: {data['summary']['total_messages']}\")
|
|
"
|
|
```
|
|
|
|
## Related Examples
|
|
|
|
- [Managing AI Actors with the CleverAgents CLI](actor-management-workflow.md) — bind sessions to specific actors
|
|
- [CleverAgents CLI Basics](cleveragents-cli-basics.md) — version, info, and diagnostics commands
|
|
- [Mastering Output Format Flags](output-format-flags.md) — deep dive into `--format json/yaml/plain/table`
|
|
- [Showcase Index](../index.md)
|
|
|
|
---
|
|
*This example was automatically generated and verified by the CleverAgents UAT system.*
|
|
*Feature area: Session management workflows | Test cycle: 1 | Generated: 2026-04-07*
|
|
|
|
---
|
|
**Automated by CleverAgents Bot**
|
|
Supervisor: UAT Testing | Agent: uat-tester
|