cleveragents-core/docs/showcase/cli-tools/session-management-workflows.md

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:

$ 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:

$ 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:

$ 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):

$ python -m cleveragents session create --actor openai/gpt-4o --format json

Actual Output:

{
  "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:

$ python -m cleveragents session list

Actual Output:

                                        Sessions
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID       ┃ Name       ┃ Actor          ┃ Messages ┃ Updated          ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 01HXYZ4M1Q3F0R0E5HR8K5T8A │ (unnamed)  │ openai/gpt-4o  │        3 │ 2026-04-07 09:22 │
│ 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ (unnamed)  │ (none)         │        0 │ 2026-04-07 09:15 │
└──────────┴────────────┴────────────────┴──────────┴──────────────────┘

╭──────────────────────────────────────────── Summary ─────────────────────────────────────────────╮
│ Total:          2                                                                                 │
│ Most Recent:    01HXYZ4M1Q3F0R0E5HR8K5T8A                                                                          │
│ Oldest:         01HXYZ3K9P2E9Q9D4GQ7J4S7Z                                                                          │
│ Total Messages: 3                                                                                 │
│ Storage:        0 KB                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

✓ OK 2 sessions listed

What's Happening: The list command renders a Rich table with five columns: the full session ULID (26 characters), 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:

$ python -m cleveragents session list --format json

Actual Output:

{
  "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": "01HXYZ4M1Q3F0R0E5HR8K5T8A",
    "oldest": "01HXYZ3K9P2E9Q9D4GQ7J4S7Z",
    "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:

$ 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:

$ 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:

$ 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:

$ 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):

$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json

Actual Output:

{
  "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:

$ 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:

{
  "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:

$ 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:

# 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:

$ 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:

$ 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

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

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

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

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

# 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

Click to see the full verified command session

$ 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": "01HXYZ4M1Q3F0R0E5HR8K5T8A", ...}}

$ 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

---

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:

  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:

  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:

  python -m cleveragents session tell --session <ID> --stream "Tell me a story."
  

• Inspect token usage across all sessions:

  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 — bind sessions to specific actors
• CleverAgents CLI Basics — version, info, and diagnostics commands
• Mastering Output Format Flags — deep dive into --format json/yaml/plain/table
• Showcase Index

---

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