cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs: align session showcase with agents CLI

Browse Source
This commit is contained in:
HAL 9000
2026-04-07 14:52:56 +00:00
committed by CleverThis
parent abc7aa413a
commit 07a4c2bac7
1 changed files with 46 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/showcase/cli-tools/session-management-workflows.md
+46 -46
View File
@@ -38,12 +38,12 @@ backup, and finally cleaning up — all from the command line.
Start by seeing what session management commands are available:
```bash
$ python -m cleveragents session --help
$ agents session --help
```
**Actual Output:**
```
Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]...
Usage: agents session [OPTIONS] COMMAND [ARGS]...
Manage interactive sessions.
@@ -74,7 +74,7 @@ unique and time-ordered, making sessions naturally sortable by creation time.
The simplest session creation — no actor bound, uses system defaults:
```bash
$ python -m cleveragents session create
$ agents session create
```
**Actual Output:**
@@ -113,7 +113,7 @@ 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
$ agents session create --actor openai/gpt-4o
```
**Actual Output:**
@@ -149,7 +149,7 @@ 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
$ agents session create --actor openai/gpt-4o --format json
```
**Actual Output:**
@@ -171,7 +171,7 @@ $ python -m cleveragents session create --actor openai/gpt-4o --format json
After creating a few sessions, list them all:
```bash
$ python -m cleveragents session list
$ agents session list
```
**Actual Output:**
@@ -205,7 +205,7 @@ storage used.
For machine-readable output:
```bash
$ python -m cleveragents session list --format json
$ agents session list --format json
```
**Actual Output:**
@@ -244,7 +244,7 @@ $ python -m cleveragents session list --format json
Use `session tell` to append a user message and receive an assistant response:
```bash
$ python -m cleveragents session tell \
$ agents session tell \
--session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
"What is the capital of France?"
```
@@ -258,7 +258,7 @@ assistant: Acknowledged: What is the capital of France?
Send a follow-up message to build conversation history:
```bash
$ python -m cleveragents session tell \
$ agents session tell \
--session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
"Now explain the Eiffel Tower's history in one sentence."
```
@@ -272,7 +272,7 @@ 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 \
$ agents session tell \
--session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
--actor anthropic/claude-sonnet-4-20250514 \
"Summarize our conversation so far."
@@ -299,7 +299,7 @@ View the complete session state including recent messages, linked plans,
and token usage:
```bash
$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
$ agents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
```
**Actual Output:**
@@ -316,13 +316,14 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 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. │
└───────────┴───────────────────────────────────────────────────────────────────────────────────────┘
Only the **five most recent** messages are displayed. The earliest prompt is omitted automatically
once the session exceeds that window.
╭──────────────────────────────────────────── Token Usage ─────────────────────────────────────────╮
│ Input Tokens: 0 │
│ Output Tokens: 0 │
@@ -334,7 +335,7 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
For JSON output (useful for scripting):
```bash
$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json
$ agents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json
```
**Actual Output:**
@@ -348,7 +349,6 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json
"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."},
@@ -380,7 +380,7 @@ Plan ID, Phase, and State columns. If a cost budget is configured, a
Export the full session data to a portable JSON file:
```bash
$ python -m cleveragents session export \
$ agents session export \
--output /tmp/my-session-backup.json \
01HXYZ4M1Q3F0R0E5HR8K5T8A
```
@@ -472,7 +472,7 @@ For human-readable sharing (e.g. documentation, code reviews), export as
Markdown:
```bash
$ python -m cleveragents session export \
$ agents session export \
--format md \
--output /tmp/my-session-transcript.md \
01HXYZ4M1Q3F0R0E5HR8K5T8A
@@ -538,7 +538,7 @@ Acknowledged: Now explain the Eiffel Tower's history in one sentence.
Restore a previously exported session:
```bash
$ python -m cleveragents session import --input /tmp/my-session-backup.json
$ agents session import --input /tmp/my-session-backup.json
```
**Actual Output:**
@@ -585,7 +585,7 @@ The import command:
Delete a session permanently with the impact summary:
```bash
$ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
$ agents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
```
**Actual Output:**
@@ -626,7 +626,7 @@ The delete command:
### Get the Most Recent Session ID
```bash
python -m cleveragents session list --format json | python3 -c "
agents session list --format json | python3 -c "
import sys, json
data = json.load(sys.stdin)
sessions = data.get('sessions', [])
@@ -641,7 +641,7 @@ else:
### Count Sessions by Actor
```bash
python -m cleveragents session list --format json | python3 -c "
agents session list --format json | python3 -c "
import sys, json
from collections import Counter
data = json.load(sys.stdin)
@@ -654,14 +654,14 @@ for actor, count in actors.most_common():
### Backup All Sessions to Individual Files
```bash
python -m cleveragents session list --format json | python3 -c "
agents 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',
'agents', 'session', 'export',
'--output', outfile, sid
])
print(f'Backed up {sid} -> {outfile}')
@@ -672,7 +672,7 @@ for session in data.get('sessions', []):
```bash
SESSION_ID="01HXYZ4M1Q3F0R0E5HR8K5T8A"
python -m cleveragents session show "$SESSION_ID" --format json | python3 -c "
agents session show "$SESSION_ID" --format json | python3 -c "
import sys, json
data = json.load(sys.stdin)
count = data['session_summary']['messages']
@@ -686,13 +686,13 @@ if count == 0:
```bash
# Create session and capture the ID
SESSION_ID=$(python -m cleveragents session create --actor openai/gpt-4o --format json \
SESSION_ID=$(agents 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 \
agents session tell \
--session "$SESSION_ID" \
"Hello! Please introduce yourself."
```
@@ -725,12 +725,12 @@ The JSON export format (schema version `1.0`) contains:
<summary>Click to see the full verified command session</summary>
```
$ python -m cleveragents session --help
Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]...
$ agents session --help
Usage: agents session [OPTIONS] COMMAND [ARGS]...
Manage interactive sessions.
Commands: create, list, show, delete, export, import, tell
$ python -m cleveragents session create
$ agents session create
╭─ Session ─╮
│ Session ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
│ Actor: (none) │
@@ -746,7 +746,7 @@ $ python -m cleveragents session create
╰─────────────────────╯
✓ OK Session created
$ python -m cleveragents session create --actor openai/gpt-4o
$ agents session create --actor openai/gpt-4o
╭─ Session ─╮
│ Session ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
│ Actor: openai/gpt-4o │
@@ -768,26 +768,26 @@ $ python -m cleveragents session create --actor openai/gpt-4o
╰──────────────────╯
✓ OK Session created
$ python -m cleveragents session list
$ agents session list
[table with 2 sessions]
✓ OK 2 sessions listed
$ python -m cleveragents session list --format json
$ agents session list --format json
{"sessions": [...], "summary": {"total": 2, "most_recent": "01HXYZ4M", ...}}
$ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "What is the capital of France?"
$ agents 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."
$ agents 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."
$ agents 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
$ agents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
╭─ Session Summary ─╮
│ ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
│ Actor: openai/gpt-4o │
@@ -804,7 +804,7 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
╰─────────────────╯
✓ OK Session details loaded
$ python -m cleveragents session export --output /tmp/my-session-backup.json 01HXYZ4M1Q3F0R0E5HR8K5T8A
$ agents session export --output /tmp/my-session-backup.json 01HXYZ4M1Q3F0R0E5HR8K5T8A
╭─ Session Export ─╮
│ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
│ Output: /tmp/my-session-backup.json │
@@ -825,11 +825,11 @@ $ python -m cleveragents session export --output /tmp/my-session-backup.json 01H
╰──────────────╯
✓ OK Export completed
$ python -m cleveragents session export --format md --output /tmp/my-session-transcript.md 01HXYZ4M1Q3F0R0E5HR8K5T8A
$ agents 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
$ agents session import --input /tmp/my-session-backup.json
╭─ Session Import ─╮
│ Input: /tmp/my-session-backup.json │
│ Session ID: 01HXYZ6Q4T6I3U3H8KU1N8W1D │
@@ -847,7 +847,7 @@ $ python -m cleveragents session import --input /tmp/my-session-backup.json
╰──────────╯
✓ OK Import completed
$ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
$ agents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
╭─ Deletion Summary ─╮
│ Session: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
│ Messages: 0 removed │
@@ -894,26 +894,26 @@ $ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
- **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!"
SID=$(agents session create --format json | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
agents 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 "
agents 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']])
subprocess.run(['agents', 'session', 'export',
'--output', f\"~/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."
agents 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 "
agents session list --format json | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"Total sessions: {data['summary']['total']}\")